Создавайте интерфейсы Google Chat

На этой странице представлен обзор того, как создавать пользовательские интерфейсы (UI) для дополнений Google Workspace, расширяющих функциональность Google Chat.

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

Для создания интерфейсов для чат-приложений используются следующие дополнительные компоненты:

• Триггеры : способы, с помощью которых пользователи Google Chat могут вызывать приложение чата, например, добавляя его в пространство или отправляя ему сообщение.
• Объекты событий : данные, которые приложения чата получают от триггеров или взаимодействий с пользовательским интерфейсом.
• Действия : Способы, которыми приложения для чата могут реагировать на взаимодействия, например, отправлять сообщения или возвращать пользовательский интерфейс на основе карточек.

Рисунок 1 : Когда пользователь добавляет приложение чата в пространство, срабатывает триггер « Добавлено в пространство» и отправляет объект события. Чтобы ответить сообщением, приложение чата обрабатывает объект события и возвращает действие, которое создает сообщение.

Приложения для чата могут создавать и отображать карточки в следующих интерфейсах:

• Сообщения , которые могут содержать текст, статические или интерактивные карточки и кнопки.
• Диалоговые окна представляют собой карточки, которые открываются в новом окне и обычно предлагают пользователям ввести информацию.
• Предварительный просмотр ссылок — это карточки, отображающие информацию о внешнем сервисе.

Триггеры

В этом разделе объясняются триггеры, которые используются дополнениями Google Workspace в чате.

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

В следующей таблице показаны триггеры чата, их описание и типичные реакции приложений чата:

Курок	Описание	Типичный ответ
Добавлено в пространство	Пользователь добавляет приложение «Чат» в пространство, или администратор Google Workspace устанавливает приложение «Чат» в пространства личных сообщений для пользователей в своей организации. Чтобы узнать о приложениях «Чат», установленных администраторами, см. раздел «Установка приложений из Marketplace в вашем домене» в документации по администрированию Google Workspace.	Приложение «Чат» отправляет вводное сообщение, в котором объясняется, что оно делает и как пользователи в данном пространстве могут с ним взаимодействовать.
Сообщение	Пользователь взаимодействует с приложением «Чат» посредством сообщения одним из следующих способов: Отправляет сообщение в личные сообщения (DM) с помощью приложения «Чат». @упоминания приложения Chat в любом типе пространства. Отправляет сообщение, содержащее ссылку, соответствующую шаблону URL для предварительного просмотра ссылок . Вводит текст в меню множественного выбора виджета selectionInput .	Приложение «Чат» отвечает в зависимости от содержимого сообщения. Например, приложение «Чат» отвечает на команду /about сообщением, в котором объясняются задачи, которые оно может выполнять.
Извлечен из космоса	Пользователь удаляет приложение «Чат» из рабочего пространства, или администратор Google Workspace удаляет приложение «Чат» для пользователя в своей организации. Пользователи не могут удалить приложения чата, установленные их администратором. Если пользователь ранее устанавливал приложение чата, оно останется установленным независимо от того, попытается ли администратор Google Workspace его удалить.	Приложение «Чат» удаляет все входящие уведомления, настроенные для данного пространства (например, удаляет веб-хук), и очищает внутреннюю память. Приложения «Чат» не могут отвечать на сообщения в ответ на этот триггер, поскольку они больше не являются участниками данного пространства.
Команда приложения	Пользователь использует команду приложения «Чат» .	Приложение «Чат» реагирует на команду. Например, отправляет ответное сообщение или открывает диалоговое окно.

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

Для реагирования на триггер см. следующие руководства:

• Отправляйте сообщения в Google Чат.
• Открыть интерактивные диалоги
• Предварительный просмотр ссылок в сообщениях Google Chat

Объекты событий

Приложения для чата получают объекты событий, когда срабатывает триггер чата или когда пользователи чата взаимодействуют с пользовательским интерфейсом приложения (например, нажимают кнопку). Объект события содержит данные о взаимодействии, которые приложение чата может использовать для ответа или обновления пользовательского интерфейса.

Чтобы узнать о работе с объектами событий, ознакомьтесь со следующими руководствами:

• Отправляйте сообщения в Google Чат.
• Открыть интерактивные диалоги
• Предварительный просмотр ссылок в сообщениях Google Chat

Чтобы узнать больше о дополнительных объектах событий в приложении «Чат» и других приложениях Google Workspace, см. раздел «Объекты событий» .

Действия в чате

В этом разделе объясняется, как приложения для чата могут использовать дополнительные действия для реагирования на действия пользователей.

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

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

Для ответа на действия пользователя приложения чата должны обрабатывать соответствующий объект события и возвращать один из следующих объектов JSON:

• DataActions : Создает или обновляет данные в Google Workspace. Для отправки или обновления сообщений чата объект должен содержать разметку, определяющую изменения данных Message , представленную как chatDataActionMarkup .
• RenderActions : Создание или обновление диалогового окна или предоставление вариантов ввода для меню с множественным выбором .
• AuthorizationError : Запрашивает у пользователей карту авторизации вход или аутентификацию в сервисе, не относящемся к Google. В чате поддерживается только базовая авторизация с помощью карты .

В следующей таблице показано, как приложения чата могут отвечать действиями. Приложения чата могут возвращать объекты JSON или формировать ответ с помощью AddOnResponseService из Apps Script.

Ответ приложения чата	Необходимое действие для возврата (JSON)	Необходимое действие для возврата (Apps Script)
Отправить или обновить сообщение .	DataActions	DataActionsResponse
Открыть, обновить или закрыть диалоговое окно .	RenderActions	ActionResponse
Для сбора информации из карточки или диалогового окна предлагайте варианты выбора на основе того, что пользователи вводят в меню с множественным выбором.	RenderActions	ActionResponse
Предварительный просмотр ссылок в сообщениях, которые пользователи чата отправляют в определенном пространстве.	DataActions	DataActionsResponse

Ответьте, используя API чата Google.

Вместо возврата действия дополнения, приложениям чата может потребоваться использовать API Google Chat для ответа на взаимодействие. Например, приложениям чата необходимо вызывать API Google Chat для выполнения любого из следующих действий:

• Ответьте на запрос через 30 секунд.
• Выполняйте задачи за пределами пространства, где происходило взаимодействие.
• Выполняйте в чате задачи, недоступные в качестве дополнительных действий. Например, выводите список пространств, в которых состоит пользователь или приложение чата, или добавляете пользователей в пространство.
• Выполняйте задачи от имени пользователя чата (для этого требуется аутентификация пользователя).

Чтобы избежать появления у пользователя сообщения об ошибке, указывающего на то, что ваше приложение чата не отвечает, при ответе на событие взаимодействия в течение 30 секунд необходимо подтвердить получение события взаимодействия, отправив пустой ответ, как показано здесь:

Node.js

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

Python

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  # Respond with an empty response to the Google Chat platform.
  return {}

Java

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

Apps Script

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

Чтобы узнать об аутентификации и вызове API чата, см. обзор API чата .

Связанные темы

• Триггеры для дополнений Google Workspace
• Настройте приложение Google Chat.
• Объекты событий
• Дополнительные действия
• Отправляйте сообщения в Google Чат.
• Открыть интерактивные диалоги
• Предварительный просмотр ссылок в сообщениях Google Chat
• Обзор API чата