Интеграция с Google Chat

Подключите вашего агента к Google Chat для удобного общения в рамках Google Workspace.

Обзор

Интеграция с Google Chat предоставляет:

• Прямые сообщения с вашим ботом
• Поддержку Google Workspace Spaces с триггерами по @упоминанию
• Маршрутизацию агентов на уровне Space — назначайте разных агентов разным Spaces
• Текстовые ответы с памятью разговора и опциональным контекстом обсуждений в Space
• Асинхронную обработку с мгновенным подтверждением получения
• Корпоративную безопасность с изоляцией на уровне домена

Предварительные требования

• Активный AI-агент (созданный в разделе Agents)
• Аккаунт Google Workspace (личные аккаунты Gmail не поддерживаются)
• Подтверждённый домен — подтвердите владение доменом в Settings > Domains перед подключением

Шаги настройки

1. Подтверждение домена (однократная настройка)

Перед подключением Google Chat подтвердите владение доменом:

1. Перейдите в Settings в боковой панели
2. Нажмите вкладку Domains
3. Ваш домен определяется автоматически по email вашего аккаунта
4. Добавьте TXT record у вашего DNS-провайдера с указанными значениями:
   • Type: TXT
   • Name: _cuneiform-verify (или полное значение, показанное на экране)
   • Content: Отображаемая строка верификации (например, cuneiform-verify=abc123...)
5. Нажмите Verify Now — изменения DNS могут занять до 48 часов для распространения
6. Когда статус изменится на Verified, переходите к созданию интеграции

На карточке верификации показаны быстрые ссылки на популярные DNS-провайдеры (Cloudflare, GoDaddy, Namecheap, Route 53, DigitalOcean, Hostinger).

2. Создание интеграции Google Chat

1. Перейдите в Integrations в боковой панели
2. В разделе “Google Chat Bots” нажмите Connect Bot
3. Выберите Agent, который будет использоваться по умолчанию для личных сообщений и непривязанных Spaces
4. Введите Bot Name (для вашего удобства в панели администратора)
5. Нажмите Connect Bot
6. Скопируйте отображённый Verification Code (формат: VERIFY-XXXXXX)

3. Завершение верификации бота

После создания интеграции вы получите код верификации:

1. Откройте Google Chat
2. Нажмите Start a chat → Find apps
3. Найдите бота платформы
4. Начните прямое сообщение с ботом
5. Отправьте код верификации (например, VERIFY-ABC123)
6. Бот подтвердит: “Setup complete! Your workspace (yourdomain.com) is now connected. Send a message to start chatting!”

Статус вашей интеграции изменится с “Pending Verification” на “Active”.

Использование бота

Прямые сообщения

Пользователи могут начать разговор:

1. Откройте Google Chat
2. Нажмите Start a chat → Find apps
3. Найдите вашего бота по имени
4. Начните общение — бот отвечает на все сообщения в личных чатах

Личные сообщения всегда обрабатываются агентом по умолчанию.

В Spaces

Добавьте бота в Space:

1. Откройте Space
2. Нажмите на имя Space → Manage apps
3. Добавьте вашего бота
4. Упоминайте бота через @Cuneiform Chat для взаимодействия — бот отвечает только на @упоминания в Spaces

Маршрутизация агентов на уровне Space

Каждый Space может опционально использовать агента, отличного от агента по умолчанию. Используйте эти команды бота в Space (требуется @упоминание):

Как работает маршрутизация:

• Личные сообщения → всегда используют агента по умолчанию
• Space с назначенным агентом → использует назначенного агента
• Space без назначенного агента → возвращается к агенту по умолчанию

Осведомлённость об истории обсуждений

По умолчанию бот видит только сообщение, в котором его непосредственно @упомянули. Если участники команды сначала отправляют контекстные сообщения (в других тредах или ранее в Space), а затем @упоминают бота, у него не будет этого контекста — если только менеджер Space не выполнит /connect.

Как это работает

1. Менеджер Space отправляет @Cuneiform Chat /connect в Space
2. Бот отправляет одноразовую ссылку для авторизации (действует 10 минут)
3. Менеджер переходит по ссылке и входит с помощью своего аккаунта Google Workspace
4. Теперь бот может читать сообщения, отправленные в Space в течение последних 15 минут перед каждым @упоминанием

После подключения при каждом @упоминании бот автоматически читает недавние сообщения Space как контекст — понимая, что команда обсуждала до его вызова.

Пример: Участники команды пишут “какие тарифные планы?” и “что входит в стартовый план?”, затем @упоминают бота с “можете помочь?” — бот видит все три сообщения и отвечает с полным контекстом.

Требования и конфиденциальность

• Только менеджеры Space (не обычные участники) могут выполнять /connect
• Авторизация выполняется для каждого Space отдельно — каждому Space нужен свой /connect
• Google OAuth токен менеджера Space шифруется и хранится безопасно
• Доступны только сообщения, видимые аккаунту менеджера
• Удаление бота из Space автоматически удаляет сохранённый токен

Повторная авторизация

Если бот теряет доступ (например, токен отозван в настройках Google-аккаунта), он уведомит Space:

⚠️ Thread history access has expired. A space manager should run /connect to restore it.

Выполните /connect снова для восстановления доступа.

Возможности

Асинхронные ответы

При отправке сообщения бот мгновенно отвечает кратким подтверждением (например, “Working on it…”), а затем доставляет полный ответ после завершения обработки. Обычно это занимает 3–8 секунд в зависимости от сложности вашего вопроса.

Память разговора

Бот запоминает контекст в рамках сессии, поэтому вы можете задавать уточняющие вопросы, не повторяя предыдущую информацию.

Контекст обсуждений в Space (опционально): После того как менеджер Space выполнит /connect, бот читает сообщения, отправленные в Space в течение последних 15 минут перед каждым @упоминанием — так он понимает, что команда уже обсуждала, без необходимости повторять контекст. См. раздел Осведомлённость об истории обсуждений для инструкций по настройке.

Очередь сообщений

Если вы отправите дополнительные сообщения, пока бот ещё обрабатывает предыдущее, они будут поставлены в очередь и включены в следующий ответ. Вы увидите сообщение вроде “I’m still working on your previous question. I’ll include this in my next response.”

Команда /help

Введите /help или help, чтобы увидеть инструкции по использованию, включая доступные команды для Space.

Доступ на основе домена

Только пользователи вашего домена Google Workspace могут взаимодействовать с вашим ботом, обеспечивая корпоративный уровень безопасности.

Текстовые ответы

Бот отвечает только текстовыми сообщениями. Изображения, файлы, интерактивные кнопки и карточки не поддерживаются. Ответы ограничены примерно 30 000 символами.

Управление интеграцией

Каждая карточка интеграции отображает:

• Bot name — Отображаемое имя, которое вы настроили
• Status badge — Active, Pending Verification или Error
• Domain name — Ваш домен Google Workspace (после верификации)
• Default agent — Выпадающий список для смены агента по умолчанию (используется для личных сообщений + непривязанных Spaces)
• Space mappings — Сворачиваемый раздел, показывающий какие Spaces имеют пользовательские назначения агентов
• Space commands — Сворачиваемый раздел с доступными командами бота
• Last activity — Временная метка последней активности

Доступные действия

Устранение неполадок

Бот не отображается в Google Chat

1. Убедитесь, что вы используете аккаунт Google Workspace (не личный Gmail)
2. Найдите имя бота в “Find apps”
3. Подождите несколько минут для распространения приложения

Раздел Google Chat не отображается

1. Google Chat отображается только для организаций, использующих Google Workspace
2. Если ваша организация использует другого почтового провайдера (например, Microsoft 365), раздел скрыт
3. Система автоматически определяет вашего почтового провайдера по MX records

Проблемы с верификацией домена

1. Изменения DNS могут занять до 48 часов для распространения — подождите и попробуйте Verify Now снова
2. Проверьте, что вы добавили TXT record с точными значениями, показанными в Settings > Domains
3. Убедитесь, что запись добавлена на правильном домене (например, _cuneiform-verify.yourdomain.com)
4. Используйте быстрые ссылки DNS-провайдеров на карточке верификации для удобного доступа

Код верификации не работает

1. Убедитесь, что вы отправляете код с email вашего Google Workspace
2. Проверьте, что код введён точно как показано (включая префикс VERIFY-)
3. Убедитесь, что интеграция всё ещё в статусе “Pending Verification”
4. Попробуйте создать новую интеграцию, если срок действия кода истёк

Бот пишет “Working on it…”, но ответ не приходит

1. Бот обрабатывает сообщения асинхронно — подождите до 25 секунд для полного ответа
2. Если ответ не приходит, попробуйте отправить сообщение ещё раз
3. Проверьте, что связанный агент правильно настроен

Сообщения не обрабатываются

1. Убедитесь, что ваше рабочее пространство верифицировано (статус должен быть “Active”)
2. В Spaces убедитесь, что вы @упоминаете бота
3. Проверьте, что связанный агент правильно настроен

Сообщение “Organization hasn’t connected”

Это означает, что бот не распознаёт ваш домен Google Workspace:

1. Ваш администратор ещё не создал интеграцию
2. Домен не был подтверждён с помощью кода верификации
3. Вы пишете с личного аккаунта Gmail (не поддерживается)

/set-agent сообщает, что агент не найден

1. Проверьте точное имя агента в панели администратора (учитывается регистр)
2. Убедитесь, что агент имеет статус “Active”
3. Имена агентов с пробелами поддерживаются — введите полное имя после /set-agent

/connect сообщает “Only space managers can run /connect”

Вы должны быть менеджером Space для выполнения /connect. Попросите менеджера вашего Space выполнить эту команду.

Ссылка авторизации /connect истекла

Ссылка действительна в течение 10 минут. Выполните @Cuneiform Chat /connect снова, чтобы получить новую ссылку.

Бот сообщает “Thread history access has expired”

Менеджеру Space необходимо выполнить @Cuneiform Chat /connect снова для повторной авторизации. Это происходит, когда Google OAuth токен отозван (например, в настройках Google-аккаунта).

Безопасность

• Верификация владения доменом — DNS TXT record подтверждает, что ваша организация владеет доменом перед подключением
• Определение Google Workspace — Проверка MX records подтверждает, что ваш домен использует Google Workspace
• Изоляция на уровне домена — только пользователи Google Workspace вашей организации могут взаимодействовать с ботом
• Верификация webhook — каждый входящий запрос проверяется по Google Cloud проекту вашей платформы
• Коды верификации одноразовые и привязаны к вашему домену
• Сообщения обрабатываются через защищённые зашифрованные соединения

Отключение

Чтобы удалить интеграцию Google Chat:

1. Перейдите в Integrations в боковой панели
2. Найдите карточку вашей интеграции Google Chat
3. Нажмите меню с тремя точками
4. Выберите Disconnect

Важные замечания

• Требуется Google Workspace: Личные аккаунты Gmail не могут использовать эту интеграцию. Если ваша организация не использует Google Workspace, раздел Google Chat не будет отображаться.
• Требуется верификация домена: Подтвердите ваш домен в Settings > Domains перед подключением Google Chat.
• Одна интеграция на организацию: Каждая организация может иметь одну интеграцию Google Chat
• Только текст: Бот не поддерживает изображения, файлы и интерактивные кнопки
• Управление на уровне организации: Google Chat настраивается на странице Integrations, а не для каждого агента отдельно
• Маршрутизация по Spaces: Используйте /set-agent в Spaces для назначения специализированных агентов разным командам
• Агент по умолчанию: Меняйте агента по умолчанию в любое время через выпадающий список — отключение не требуется