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

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

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

  • Триггеры : способы, с помощью которых пользователи Google Chat могут вызывать приложение чата, например, добавляя его в пространство или отправляя ему сообщение.
  • Объекты событий : данные, которые приложения чата получают от триггеров или взаимодействий с пользовательским интерфейсом.
  • Действия : Способы, которыми приложения для чата могут реагировать на взаимодействия, например, отправлять сообщения или возвращать пользовательский интерфейс на основе карточек.
Приложение чата получает объект события от триггера "Добавлено в пространство".
Figure 1 : When a user adds a Chat app to a space, the Added to space trigger fires and sends an event object. To respond with a message, the Chat app handles the event object and returns an action that creates the message.

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

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

Триггеры

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

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

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

Курок Описание Типичный ответ
Добавлено в пространство

A user adds the Chat app to a space, or a Google Workspace administrator installs the Chat app in direct message spaces for users in their organization. To learn about Chat apps installed by administrators, see Install Marketplace apps in your domain in the Google Workspace Admin Help documentation.

 Приложение «Чат» отправляет вводное сообщение, в котором объясняется, что оно делает и как пользователи в данном пространстве могут с ним взаимодействовать.
Сообщение

Пользователь взаимодействует с приложением «Чат» посредством сообщения одним из следующих способов:

  • Отправляет сообщение в личные сообщения (DM) с помощью приложения «Чат».
  • @упоминания приложения Chat в любом типе пространства.
  • Отправляет сообщение, содержащее ссылку, соответствующую шаблону URL для предварительного просмотра ссылок .
  • Вводит текст в меню множественного выбора виджета selectionInput .
 Приложение «Чат» отвечает в зависимости от содержимого сообщения. Например, приложение «Чат» отвечает на команду /about сообщением, в котором объясняются задачи, которые оно может выполнять.
Извлечен из космоса

Пользователь удаляет приложение «Чат» из рабочего пространства, или администратор Google Workspace удаляет приложение «Чат» для пользователя в своей организации.

Users can't remove Chat apps that were installed by their administrator. If a user had previously installed the Chat app, Chat app remains installed regardless of whether an Google Workspace administrator tries to uninstall.

 The Chat app removes any incoming notifications configured for the space (such as deleting a webhook) and clears up any internal storage. Chat apps can't respond with messages to this trigger, because they're no longer a member of the space.
Команда приложения

Пользователь использует команду приложения «Чат» .

 Приложение «Чат» реагирует на команду. Например, отправляет ответное сообщение или открывает диалоговое окно.

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

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

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

Chat apps receive event objects when a Chat trigger fires, or when Chat users interact with a UI from the Chat app (such as clicking a button). The event object lets you use interaction data to respond or update a UI.

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

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

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

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

To respond with an add-on action, a Chat app must respond within 30 seconds, and the response must be posted in the space where the interaction occurred. Otherwise, the Chat app must set up authentication and call the Google Chat API to respond.

Chat apps can handle and respond to interactions in many ways. In many cases, Chat apps reply with a message. Chat apps can also look up some information from a data source, record the event object information, or just about anything else. This processing behavior is essentially what defines the Google Chat app.

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

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

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

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

Instead of returning an add-on action, Chat apps might need to use the Google Chat API respond to an interaction. For example, Chat apps must call the Google Chat API to do any of the following:

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

When responding to an interaction event after 30 seconds, to avoid a user-facing error message saying your Chat app isn't responding, you must acknowledge receipt of an interaction event within 30 seconds by sending an empty response, as shown here:

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 чата .