Как настроить Google Chat API

Для каждого создаваемого приложения Google Chat требуется отдельный проект Google Cloud с включенным и настроенным Chat API.

Чтобы выполнять вызовы API только для чтения с аутентификацией пользователя, например получать чат-группы и списки сообщений, вам нужно только включить API и создать клиента OAuth.

Чтобы выполнять вызовы API для создания, обновления и удаления, а также развертывать и тестировать интерактивное приложение Chat (созданное как дополнение Google Workspace, расширяющее Chat), необходимо также настроить Chat API. В настройках конфигурации Chat API можно указать все сведения о приложении Chat, в том числе его отображаемое название, аватар, конечные точки развертывания и интерактивные функции.

Требования

• Аккаунт Google Workspace версии Business или Enterprise с доступом к Google Chat.
• Создайте проект Google Cloud.
• Настройте окно запроса доступа OAuth.
• Включите Google Chat API.

Как выбрать отображаемое название, аватар и описание для приложения Chat

Когда вы включаете Chat API, вы настраиваете сведения о приложении Chat, которые будут показываться пользователям в Chat, в том числе отображаемое название, аватар и описание. Эти данные показываются только в Chat. Чтобы опубликовать приложение Chat в каталоге Marketplace, вам также нужно указать сведения, которые будут показываться на странице приложения в каталоге.

Прежде чем настраивать приложение Chat, подготовьте следующую информацию:

Поле	Описание	Формат
Название приложения	Отображаемое название приложения Chat.	До 25 буквенно-цифровых символов.
URL аватара	Изображение, которое будет использоваться в качестве аватара приложения Chat.	URL с протоколом HTTPS, ведущий на квадратное изображение в формате PNG или JPEG. Рекомендуемый размер – 256 x 256 пикселей или больше.
Описание	Краткое описание назначения приложения Chat.	До 40 буквенно-цифровых символов.

Название, аватар и описание приложения Chat показываются пользователям в интерфейсе Chat. В некоторых запросах на запись Chat API Chat использует эту информацию, чтобы приписывать действия, которые приложение Chat выполняет в Chat.

Например, если вы вызываете метод spaces.create(), Chat включает название приложения Chat в описание того, кто создал чат-группу, как показано на следующем изображении:

Рисунок 1. Сообщение об авторстве, которое Chat показывает, когда метод spaces.create() используется для создания чат-группы от имени пользователя.

Чтобы взаимодействовать с приложениями Chat, пользователи также могут просматривать или использовать эту информацию следующими способами:

• @упомяните приложение Chat, чтобы добавить его в чат-группу или отправить ему сообщение.
• Найдите приложение Chat и начните с ним прямую переписку. В меню Приложения прямые переписки отображаются с названием и аватаром приложения Chat.
• В поле чата пользователи могут просматривать приложения Chat, а также их названия, аватары и описания.

Как настроить приложение Chat в консоли Google Cloud

Когда у вас появятся сведения о приложении Chat, откройте облачный проект и настройте Chat API:

1. В консоли Google Cloud перейдите на страницу Chat API и нажмите Configuration (Настройки):

   Перейти на страницу конфигурации Chat API

2. В разделе Информация о приложении заполните поля Название приложения, URL аватара и Описание.

3. В разделе Интерактивные функции настройте, будет ли приложение Chat отвечать на действия пользователей:

   Примечание. Если ваше приложение Chat вызывает только Chat API и не получает ответы от пользователей, оставьте параметр Включить интерактивные функции отключенным и перейдите к следующему шагу.

   Чтобы создать интерактивное приложение Chat, включите параметр Включить интерактивные функции и выполните следующие действия:

   1. В разделе Функциональность:
      • При необходимости выберите Поддержка главного экрана приложения, чтобы на вкладке Главная в прямых переписках с приложением Chat показывалась карточка на главном экране.
      • Выберите Присоединяться к чат-группам и групповым чатам, чтобы ваше приложение для Chat можно было установить и использовать. По умолчанию пользователи могут устанавливать приложение Chat и обмениваться сообщениями с ним в отдельной чат-группе. Также пользователи могут добавлять приложение Chat в чат-группы с несколькими участниками и взаимодействовать с ним.

   2. В разделе Настройки подключения выберите архитектуру, которую хотите использовать для получения объектов событий из Chat:

      • Чтобы использовать сервис HTTP, выберите URL конечной точки HTTP и укажите URL.
      • Чтобы использовать проект Google Apps Script, выберите Apps Script и укажите идентификатор развертывания для проекта.
      • Чтобы использовать агента Dialogflow, выберите Dialogflow, а затем Dialogflow CX или Dialogflow ES и укажите название ресурса агента.
      • Чтобы использовать Pub/Sub, выберите Cloud Pub/Sub и введите название темы.
      Предупреждение. Если идентификатор развертывания Apps Script уже указан, проект Cloud связан с существующим дополнением Google Workspace. Если вы измените идентификатор развертывания в Chat API, он обновится для вашего дополнения и может повлиять на его страницу в Google Workspace Marketplace. Чтобы проверить конфигурацию дополнения, ознакомьтесь с разделом Настройка приложения в Google Workspace Marketplace SDK.

   3. Чтобы направить объекты событий в определенные конечные точки или функции, перейдите в раздел Настройки подключения > Триггеры и укажите или обновите конечные точки обратного вызова или функции для следующих триггеров чата:

      Примечание. Если вы не обновите триггеры в Apps Script, вам нужно будет реализовать функции обратного вызова по умолчанию, которые указаны в этом разделе (например, onMessage, onAddedToSpace, onRemovedFromSpace, onAppCommand и onAppHome).
      • Главная страница приложения (если включена функция Поддержка главной страницы приложения). Пользователь открывает вкладку Главная в прямой переписке с приложением Chat.
      • Добавлено в чат-группу. Пользователь добавляет приложение Chat в групповой чат или чат-группу или устанавливает приложение Chat для прямых переписок.
      • Сообщение. Пользователь отправляет сообщение приложению Chat. Например, пользователь отправляет прямое сообщение приложению Chat или упоминает приложение Chat в чат-группе с несколькими участниками.
      • Удалено из чат-группы. Пользователь удалил приложение Chat из чат-группы.
      • Команда приложения. Пользователь вызывает быструю команду, слеш-команду или действие с сообщением из приложения Chat.

   4. При необходимости добавьте другие интерактивные функции, например варианты запросов, команды (быстрые команды, слеш-команды и действия с сообщениями) или предварительный просмотр ссылок.

   5. В разделе Видимость укажите свой адрес электронной почты, чтобы установить и протестировать приложение Chat перед публикацией в Google Workspace Marketplace. Вы можете указать до пяти пользователей или одну или несколько групп Google из вашей организации Google Workspace.

4. Необязательно: в разделе Журналы установите флажок Регистрировать ошибки в Logging, чтобы использовать Google Cloud Logging. Подробнее о том, как запрашивать журналы ошибок для приложений Chat…

5. Нажмите Сохранить.

После сохранения конфигурации все, кто указан в настройке Видимость Chat API, смогут установить, протестировать или использовать приложение Chat. Чтобы начать тестирование и отладку приложения Chat, ознакомьтесь со статьей Как тестировать интерактивные функции приложений Google Chat.

Рекомендации по использованию существующих дополнений Google Workspace

Приложения Chat требуют другой конфигурации по сравнению с дополнениями Google Workspace, которые расширяют другие приложения Google Workspace. Если ваше дополнение расширяет другие приложения Google Workspace, при настройке приложения Chat учитывайте следующие требования:

• Как обычные пользователи, так и администраторы Google Workspace должны иметь возможность установить ваше дополнение из Marketplace. Эти настройки установки задаются в Google Workspace Marketplace SDK.
• Приложения Chat не используют название и логотип, которые вы настраиваете для других приложений Google Workspace в объекте addons.common манифеста.
• Для дополнений, опубликованных в Google Workspace Marketplace, нельзя сохранить черновик изменений в настройках конфигурации Google Chat API. После того как вы обновите и сохраните настройки конфигурации Chat API, обновленное приложение Chat сразу станет доступно всем существующим пользователям. Чтобы изменить страницу приложения в каталоге, вы можете создать черновик, прежде чем отправлять изменения.
• Если вы создали дополнение с помощью Apps Script:
  • Используйте тот же идентификатор развертывания Apps Script, что и для остальной конфигурации дополнения.
  • Установить тестовые развертывания в Chat с помощью редактора Apps Script нельзя. Вместо этого вам нужно установить их непосредственно из интерфейса Chat.
• Если вы создали дополнение с помощью HTTP-сервиса, не указывайте в манифесте и развертываниях, созданных с помощью Google Workspace Add-ons API, сведения о конфигурации приложения Chat. Развертывания HTTP, указанные в Google Workspace Marketplace SDK, используются только для других приложений Google Workspace.

Как предоставить другим пользователям разрешение на настройку API Chat

Вы можете предоставить определенным пользователям доступ к странице конфигурации приложения Chat, назначив им роль владельца приложений Chat или роль наблюдателя приложений Chat Google Cloud Identity Access Management (IAM). Пользователи с этими ролями не могут перейти на страницу конфигурации приложений Chat с помощью панели управления API и сервисы, но могут открыть ее, перейдя в консоль Google Cloud для хост-облачного проекта приложения Chat следующим образом:

https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

где PROJECT_ID – идентификатор проекта Google Cloud, в котором размещено приложение Chat.

Пользователи с ролями Проекта также могут получить доступ к странице конфигурации приложения.

Пользователи со специальными ролями, содержащими разрешения resourcemanager.projects.(get|update), не могут получить доступ к конфигурации приложения Chat. Для специальных ролей используйте разрешения chat.bots.(get|update).

Статьи по теме

• Как выбрать архитектуру приложения Chat
• Как получать и обрабатывать действия пользователей
• Как тестировать интерактивные функции приложений Google Chat

Приложения для Chat, которые не являются дополнениями: настройте Google Chat API

Если вы поддерживаете приложение Chat, которое не является дополнением Google Workspace, в вашей конфигурации используется одна конечная точка для всех событий взаимодействия, а не триггеры для каждого события:

1. В консоли Google Cloud перейдите на страницу Configuration (Конфигурация) Chat API:

   Перейти на страницу конфигурации Chat API

2. В разделе Интерактивные функции включите параметр Включить интерактивные функции.

3. Снимите флажок Создать это приложение Chat как дополнение Google Workspace. Откроется диалоговое окно с запросом на подтверждение. В диалоговом окне нажмите Отключить.

4. В разделе Функциональность выберите Поддержка главной страницы приложения или Присоединяться к чат-группам и групповым чатам.

5. В разделе Настройки подключения укажите одну конечную точку для приложения Chat (URL конечной точки HTTP, идентификатор развертывания Apps Script, название темы Cloud Pub/Sub или Dialogflow).

6. Настройте необязательные параметры Команды, Предпросмотр ссылок, Видимость и Журналы, а затем нажмите Сохранить.

Чтобы преобразовать приложение Chat, которое не является дополнением, в дополнение Google Workspace, расширяющее возможности Google Chat, ознакомьтесь со статьей Как преобразовать приложение Google Chat в дополнение Google Workspace.