Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Как настроить 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 в описание того, кто создал чат-группу, как показано на следующем изображении:

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

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

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

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

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

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

Перейти на страницу конфигурации Chat API
В разделе Application info (Информация о приложении) заполните поля App name (Название приложения), Avatar URL (URL аватара) и Description (Описание).
Необязательно. В меню Синтаксис разметки выберите синтаксис разметки по умолчанию (Markdown или Chat) для сообщений приложения Chat. Подробнее о форматировании текста и о том, как Chat определяет синтаксис разметки для запросов к API…
В разделе Интерактивные функции укажите, должно ли приложение 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.
При необходимости в разделе Журналы установите флажок Записывать ошибки в журнал, чтобы использовать Google Cloud Logging. Подробнее о запросах к журналам ошибок в приложениях для Chat…
Нажмите Сохранить.

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

Как настроить приложение Chat с помощью Google Workspace Add-ons API

Вместо того чтобы настраивать приложение Chat вручную в консоли Google Cloud, вы можете использовать облачный проект Google Cloud, зарегистрированный в программе предварительной версии для разработчиков Google Workspace, чтобы программно считывать и обновлять конфигурацию приложения Chat, созданного как дополнение Google Workspace, с помощью ресурса chatAppConfig в Google Workspace add-ons API.

chatAppConfig – это ресурс-одиночка, который всегда существует для каждого облачного проекта. До первого сохранения конфигурации ресурс содержит пустую конфигурацию (это же возвращает метод GetChatAppConfig, если вы прочитаете ресурс до первого сохранения). Поскольку ресурс уже существует, вам не нужно создавать его отдельно. Используйте UpdateChatAppConfig как для сохранения исходной конфигурации, так и для обновления существующей.

Предварительные требования и аутентификация

Прежде чем вызывать GetChatAppConfig или UpdateChatAppConfig, выполните следующие предварительные требования:

Зарегистрируйте проект Google Cloud в программе предварительного доступа для разработчиков Google Workspace.
Включите Google Workspace Add-ons API (gsuiteaddons.googleapis.com) в своем облачном проекте. При необходимости вы можете включить Google Chat API (chat.googleapis.com), чтобы просматривать или обновлять конфигурацию приложения Chat в консоли Google Cloud или вызывать Chat API.
Выполните аутентификацию как пользователь с учетными данными OAuth 2.0, которые включают область действия https://www.googleapis.com/auth/cloud-platform. Аутентификация сервисного аккаунта не поддерживается для методов chatAppConfig.
Убедитесь, что у аутентифицированного пользователя есть необходимые разрешения Identity and Access Management (IAM) в целевом облачном проекте:
- gsuiteaddons.chatAppConfigs.get и chat.bots.get для чтения конфигурации (GetChatAppConfig).
- gsuiteaddons.chatAppConfigs.update и chat.bots.update, чтобы обновить конфигурацию (UpdateChatAppConfig).
Если вы используете клиентскую библиотеку, скачайте ее предварительную версию для разработчиков, используя зарегистрированный аккаунт с доступом к предварительной версии.

Как обновить конфигурацию приложения Chat

Чтобы настроить приложение Chat в первый раз или обновить существующую конфигурацию, отправьте запрос PATCH (UpdateChatAppConfig) к ресурсу-одиночке chatAppConfig для вашего облачного проекта.

Для первоначального сохранения облачного проекта с пустым полем chatAppConfig необходимо указать displayName (от 3 до 25 символов) и description (от 1 до 40 символов). Если вы не укажете interactiveFeatureConfig при первом сохранении, приложение Chat будет настроено как неинтерактивное.
Для последующих обновлений используйте необязательный параметр запроса updateMask, чтобы указать разделенные запятыми поля для обновления (или опустите updateMask, чтобы обновить все предоставленные поля). При обновлении повторяющегося поля (appCommands, urlPatterns или allowlistedTestingPrincipals) заменяется весь список.

PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "name": "projects/PROJECT_NUMBER/chatAppConfig",
  "displayName": "Cymbal Assistant",
  "description": "Helps manage tasks and schedules",
  "avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
  "state": "ACTIVE",
  "errorLoggingEnabled": true,
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "interactiveFeatureConfig": {
    "supportsMultiuserSpaces": false,
    "connectionConfig": {
      "httpEndpointConfig": {
        "commonUrl": "https://example.com/chat"
      }
    },
    "appCommands": [
      {
        "commandType": "SLASH_COMMAND",
        "commandId": 1,
        "command": "/help",
        "description": "Show available commands",
        "dialogEnabled": false
      }
    ],
    "urlPatterns": [
      {
        "hostPattern": "example.com",
        "pathPrefix": "tasks/"
      }
    ],
    "allowlistedTestingPrincipals": [
      "USER_EMAIL"
    ]
  }
}

Замените в URL, заголовке и теле запроса следующие значения:

PROJECT_NUMBER – числовой номер облачного проекта, в котором размещено ваше приложение Chat.
ACCESS_TOKEN – токен доступа OAuth 2.0 пользователя, авторизованный с областью действия https://www.googleapis.com/auth/cloud-platform.
USER_EMAIL – адрес электронной почты или группа Google из вашей организации Google Workspace, которую нужно добавить в белый список для тестирования приложения Chat (например, ваш собственный адрес электронной почты).
Примеры полей конфигурации в теле запроса (такие как displayName, description, avatarUri и interactiveFeatureConfig, включая конфигурацию конечной точки, команды, шаблоны URL для предварительного просмотра ссылок и тестирования субъектов) со значениями для вашего приложения Chat. Подробные сведения обо всех поддерживаемых полях и параметрах конечных точек см. в справочнике по REST projects.chatAppConfig и projects.chatAppConfig.patch.

Как получить конфигурацию приложения Chat

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

BASIC (по умолчанию) – возвращает основные метаданные без interactiveFeatureConfig.
FULL – возвращает все поля конфигурации, включая interactiveFeatureConfig.

Если конфигурация приложения Chat ещё не сохранена для облачного проекта, метод возвращает пустой объект ChatAppConfig.

HTTP

GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN

Node.js

const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;

const client = new GSuiteAddOnsClient();

async function getChatAppConfig() {
  const [response] = await client.getChatAppConfig({
    name: 'projects/PROJECT_NUMBER/chatAppConfig',
    view: 'FULL',
  });
  console.log(JSON.stringify(response, null, 2));
}

getChatAppConfig();

Python

from google.cloud import gsuiteaddons_v1

client = gsuiteaddons_v1.GSuiteAddOnsClient()

request = gsuiteaddons_v1.GetChatAppConfigRequest(
    name="projects/PROJECT_NUMBER/chatAppConfig",
    view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)

Что нужно учитывать при работе с существующими дополнениями Google Workspace

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

Как отдельные пользователи, так и администраторы Google Workspace должны иметь возможность установить ваше дополнение из Marketplace. Эти настройки задаются в 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 в манифесте projects.deployments, который вы создаете с помощью Google Workspace Add-ons API. Развертывания HTTP, которые вы указываете в Google Workspace Marketplace SDK, используются только для других приложений Google Workspace. Вместо этого настройте приложение Chat в консоли Google Cloud или с помощью ресурса chatAppConfig в Google Workspace add-ons API.

Как предоставить другим пользователям разрешение на настройку 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.

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

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

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

Перейти на страницу конфигурации Chat API
В разделе Интерактивные функции включите параметр Включить интерактивные функции.
Снимите флажок Создать это приложение Chat как дополнение Google Workspace. Появится диалоговое окно с запросом на подтверждение. В диалоговом окне нажмите Отключить.
В разделе Функциональность выберите Поддержка главного экрана приложения или Присоединение к чат-группам и групповым чатам.
В разделе Настройки подключения укажите одну конечную точку для приложения Chat (URL конечной точки HTTP, идентификатор развертывания Apps Script, название темы Cloud Pub/Sub или Dialogflow).
При необходимости настройте команды, предварительный просмотр ссылок, видимость и журналы, а затем нажмите Сохранить.

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