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

Предварительная версия для разработчиков: доступна в рамках программы Google Workspace Developer Preview Program , которая предоставляет ранний доступ к определенным функциям.

На этой странице представлен обзор того, как создавать пользовательские интерфейсы (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-адреса для предварительного просмотра ссылок . Вводит текст в меню множественного выбора виджета selectionInput .	Приложение Chat отвечает в зависимости от содержания сообщения. Например, приложение Chat отвечает на команду косой черты /about сообщением, объясняющим задачи, которые может выполнять приложение Chat.
Удален из космоса	Пользователь удаляет приложение Chat из пространства, или администратор Google Workspace удаляет приложение Chat для пользователя в своей организации. Пользователи не могут удалять приложения чата, установленные их администратором. Если пользователь ранее установил приложение Chat, приложение Chat останется установленным независимо от того, попытается ли администратор Google Workspace удалить его.	Приложение Chat удаляет все входящие уведомления, настроенные для этого пространства (например, удаление веб-перехватчика), и очищает всю внутреннюю память. Приложения чата не могут отвечать сообщениями на этот триггер, поскольку они больше не являются участниками пространства.
Команда приложения	Пользователь использует команду приложения Chat .	Приложение «Чат» реагирует на команду. Например, отвечает сообщением или открывает диалог.

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

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

• Отправлять сообщения в 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.appCommandPayload	object ( AppCommandPayload ) Полезные данные, которые получают приложения чата, когда пользователь использует команду из приложения чата.

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

В зависимости от типа взаимодействия событие содержит полезную нагрузку с одним или несколькими ресурсами 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 в пространство с помощью сообщения. Например, @упоминает приложение Chat или использует команду. Если true , Chat отправляет другой объект события с messagePayload , содержащим информацию о сообщении.

Удалена из космического груза

Удалено из космоса
chat.removedFromSpacePayload.space	object ( Space ) Пространство чата, из которого пользователь удалил или удалил приложение чата. Когда администраторы удаляют приложения 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 ) Пространство чата, в котором произошло взаимодействие.

Полезная нагрузка команды приложения

AppCommandПолезная нагрузка
chat.appCommandPayload.appCommandMetadata	object ( AppCommandMetadata ) Метаданные о том, какую команду использовал пользователь и как он вызвал эту команду.
chat.appCommandPayload.space	object ( Space ) Пространство чата, в котором пользователь использовал команду.
chat.appCommandPayload.thread	object ( Thread ) Если взаимодействие произошло в потоке, это поток чата, в котором пользователь использовал команду.
chat.appCommandPayload.message	object ( Message ) Для косой черты — сообщение, содержащее косую черту.
chat.appCommandPayload.configCompleteRedirectUri	string Если для команды требуется авторизация или настройка, URL-адрес, на который будет перенаправлен пользователь после завершения процесса за пределами Google Chat.
chat.appCommandPayload.isDialogEvent	boolean Открывает ли команда диалоговое окно .
chat.appCommandPayload.dialogEventType	enum ( DialogEventType ) Тип взаимодействия с диалогом.
Перечисление DialogEventType . Значение dialogEventType может быть только одним из следующих:
TYPE_UNSPECIFIED	Значение по умолчанию. Не указано.
REQUEST_DIALOG	Пользователь запрашивает диалог. Например, они используют команду или нажимают кнопку из сообщения.
SUBMIT_DIALOG	Пользователь щелкает интерактивный элемент в диалоговом окне. Например, пользователь заполняет информацию в диалоговом окне и нажимает кнопку, чтобы отправить информацию.

Метаданные команды приложения

AppCommandМетаданные
chat.appCommandPayload.appCommandMetadata.appCommandId	string ( int64 format) Идентификатор команды.
chat.appCommandPayload.appCommandMetadata.appCommandType	enum ( AppCommandType ) Тип команды.
Перечисление AppCommandType . Значение AppCommandType может быть только одним из следующих:
APP_COMMAND_TYPE_UNSPECIFIED	Значение по умолчанию. Не указано.
SLASH_COMMAND	Пользователь использует команду, отправляя сообщение, которое начинается с косой черты / .

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

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

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

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

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

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

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

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

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

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

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

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

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