Как настроить 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, необходимо также указать сведения, которые будут показываться на странице приложения в Marketplace.

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

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

Название, аватар и описание приложения Chat показываются пользователям в интерфейсе Chat. Для некоторых запросов на запись Chat API использует эту информацию, чтобы соотносить действия, которые приложение 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. В разделе Application info (Информация о приложении) заполните поля App name (Название приложения), Avatar URL (URL аватара) и Description (Описание).

3. Необязательно. В меню Синтаксис разметки выберите синтаксис разметки по умолчанию (Markdown или Chat) для сообщений приложения Chat. Подробнее о форматировании текста и о том, как Chat определяет синтаксис разметки для запросов к API…

4. В разделе Интерактивные функции укажите, должно ли приложение 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 уже указан, значит облачный проект подключен к существующему дополнению Google Workspace. Если вы обновите идентификатор развертывания в Chat API, он также будет обновлен для вашего дополнения, что может повлиять на его страницу в Google Workspace Marketplace. Чтобы проверить конфигурацию дополнения, ознакомьтесь со статьей Как настроить приложение в Google Workspace Marketplace SDK.

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

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

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

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

5. При необходимости в разделе Журналы установите флажок Записывать ошибки в журнал, чтобы использовать Google Cloud Logging. Подробнее о запросах к журналам ошибок в приложениях для Chat…

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

После сохранения конфигурации все, кого вы указали в настройке Видимость 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 сразу станет доступно всем существующим пользователям. Чтобы обновить страницу продукта в Marketplace, вы можете создать черновик, прежде чем отправлять изменения.
• Если вы создали дополнение с помощью Apps Script:
  • Вы должны использовать тот же идентификатор развертывания Apps Script, который вы используете для остальной части конфигурации вашего дополнения.
  • Вы не можете использовать редактор Apps Script для установки тестовых развертываний в Chat. Вместо этого вам нужно установить их непосредственно из интерфейса Chat.
• Если вы создали дополнение с помощью HTTP-сервиса, не указывайте сведения о конфигурации приложения Chat в манифесте и развертываниях, созданных с помощью Google Workspace Add-ons API. Развертывания HTTP, которые вы указываете в Google Workspace Marketplace SDK, используются только для других приложений Google Workspace.

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

Вы можете предоставить определенным пользователям доступ к странице конфигурации приложения Chat, назначив им роль Google Cloud Identity Access Management (IAM) Владелец приложений Chat или Наблюдатель приложений Chat. Пользователи с этими ролями не могут перейти на страницу конфигурации приложений 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.