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

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

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

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

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

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

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

Триггеры

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

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

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

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

Пользователь добавляет приложение Chat в пространство, или администратор Google Workspace устанавливает приложение Chat в пространствах прямых сообщений для пользователей в своей организации. Дополнительную информацию о приложениях Chat, установленных администраторами, можно найти в разделе «Установка приложений Marketplace в вашем домене» в справочной документации администратора Google Workspace.

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

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

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

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

Пользователи не могут удалить приложения чата, установленные их администратором. Если пользователь ранее установил приложение Chat, приложение Chat останется установленным независимо от того, попытается ли администратор Google Workspace удалить его.

 Приложение Chat удаляет все входящие уведомления, настроенные для этого пространства (например, удаление веб-перехватчика), и очищает всю внутреннюю память. Приложения чата не могут отвечать сообщениями на этот триггер, поскольку они больше не являются участниками пространства.

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

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

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

В этом разделе определяются и объясняются все элементы объектов событий чата. Дополнительные сведения см. в разделе Объекты событий .

Объект события
commonEventObject object ( CommonEventObject )
Объект, содержащий информацию, общую для всех объектов событий, независимо от хост-приложения.
chat object ( Chat )
Объект, содержащий всю информацию о взаимодействиях в чате.

Чат

Чат
chat.user object ( User )
Пользователь чата, который взаимодействовал с приложением чата.
chat.space object ( Space )
Пространство чата, в котором пользователь взаимодействовал с приложением чата.
chat.eventTime

string ( Timestamp format)

Время, когда произошло взаимодействие.

payload Union Field.

payload может быть только одной из следующих:

chat.messagePayload

object ( MessagePayload )

Полезная нагрузка, которую приложения чата получают от триггера сообщения .

chat.addedToSpacePayload

object ( AddedToSpacePayload )

Полезная нагрузка, которую приложения чата получают от триггера «Добавлено в пространство» .

chat.removedFromSpacePayload

object ( RemovedFromSpacePayload )

Полезная нагрузка, которую приложения чата получают от триггера «Удалено из космоса» .

chat.buttonClickedPayload

object ( ButtonClickedPayload )

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

chat.widgetUpdatedPayload

object ( WidgetUpdatedPayload )

Полезная нагрузка, которую получают приложения чата, когда пользователи вводят текст в меню множественного выбора виджета selectionInput . Приложения чата могут использовать этот объект события для заполнения предлагаемых элементов из динамического источника данных. Например, чтобы заполнить заявки на поддержку из внешнего источника данных, приложение Chat может запросить источник данных на основе того, что пользователь вводит в меню, а затем вернуть любые соответствующие заявки на поддержку в качестве выбираемых элементов.

Объект CommonEventObject.parameters['autocomplete_widget_query'] содержит строковое значение, которое пользователь вводит в меню.

Полезная нагрузка

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

Полезная нагрузка сообщения
Полезная нагрузка сообщения
chat.messagePayload.message object ( Message )
Сообщение чата, вызвавшее событие.
chat.messagePayload.space object ( Space )
Пространство чата, в котором пользователь отправил сообщение, вызвавшее приложение чата.

Добавлен в космическую полезную нагрузку
Добавлено в пространство
chat.addedToSpacePayload.space object ( Space )
Пространство чата, в которое пользователь добавил или установил приложение чата.

Когда администраторы устанавливают приложения Chat, для поля space.adminInstalled установлено значение true .

chat.addedToSpacePayload.interactionAdd boolean
Добавляет ли пользователь приложение Chat в пространство с помощью сообщения. Например, @упоминает приложение «Чат» или использует косую черту. Если true , Chat отправляет другой объект события с messagePayload , содержащим информацию о сообщении.

Удалена из космического груза
Удалено из космоса
chat.removedFromSpacePayload.space object ( Space )
Пространство чата, из которого пользователь удалил или удалил приложение Chat.

Когда администраторы удаляют приложения Chat, для поля space.adminInstalled установлено значение false .

Полезная нагрузка при нажатии кнопки
ButtonClickedПолезная нагрузка
chat.buttonClickedPayload.message object ( Message )
Сообщение чата, содержащее кнопку, которую нажал пользователь.
chat.buttonClickedPayload.space object ( Space )
Пространство чата, в котором пользователь нажал кнопку в сообщении приложения чата.
chat.buttonClickedPayload.isDialogEvent boolean
Нажал ли пользователь кнопку для взаимодействия с диалоговым окном .
chat.buttonClickedPayload.dialogEventType enum ( DialogEventType )
Если isDialogEvent имеет true , тип взаимодействия в диалоговом окне.

Перечисление DialogEventType .

Значение dialogEventType может быть только одним из следующих:

TYPE_UNSPECIFIED Значение по умолчанию. Не указано.
REQUEST_DIALOG Пользователь запрашивает диалог. Например, они используют косую черту или нажимают кнопку в сообщении.
SUBMIT_DIALOG Пользователь щелкает интерактивный элемент в диалоговом окне. Например, пользователь заполняет информацию в диалоговом окне и нажимает кнопку, чтобы отправить информацию.

Полезные данные виджета обновлены.
ВиджетОбновленПолезная нагрузка
chat.widgetUpdatedPayload.space object ( Space )
Пространство чата, в котором произошло взаимодействие.

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

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

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

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

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

Желаемый ответ приложения чата Необходимое действие для возврата
Отправьте или обновите сообщение . DataActions
Открыть, обновить или закрыть диалоговое окно . RenderActions
Чтобы собрать информацию из карточки или диалогового окна, предложите элементы выбора на основе того, что пользователи вводят в меню с множественным выбором. RenderActions
Предварительный просмотр ссылок в сообщениях, которые пользователи Chat отправляют в группу. DataActions

Ответить с помощью Google Chat API

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

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

Дополнительные сведения об аутентификации и вызове Chat API см. в обзоре Chat API .