На этой странице представлен обзор того, как создавать пользовательские интерфейсы (UI) для надстроек Google Workspace, расширяющих Google Chat.
В Google Chat дополнения отображаются пользователям как приложения Google Chat. Дополнительную информацию см. в обзоре расширения Google Chat .
Для создания интерфейсов для приложений чата вы используете следующие дополнительные компоненты:
- Триггеры : способы, с помощью которых пользователи Google Chat могут вызвать приложение Chat, например добавить его в пространство или отправить ему сообщение.
- Объекты событий : данные, которые приложения чата получают от триггеров или взаимодействий пользовательского интерфейса.
- Действия : способы, которыми приложения чата могут реагировать на взаимодействия, например отправку сообщений или возврат пользовательского интерфейса на основе карточек.
Приложения чата могут создавать и отображать карточки в следующих интерфейсах:
- Сообщения , которые могут содержать текст, статические или интерактивные карточки и кнопки.
- Диалоги , представляющие собой карточки, которые открываются в новом окне и обычно предлагают пользователям предоставить информацию.
- Предварительный просмотр ссылок — это карточки, на которых просматривается информация о внешней службе.
Триггеры
В этом разделе описаны триггеры, которые надстройки Google Workspace используют в Chat.
Триггеры — это особые способы, с помощью которых пользователи вызывают приложение чата с помощью пользовательского интерфейса чата, например с помощью @mentions или команд приложения.
В следующей таблице показаны триггеры Chat, их описание и типичная реакция приложений Chat:
| Курок | Описание | Типичный ответ |
|---|---|---|
| Добавлено в космос | Пользователь добавляет приложение Chat в пространство, или администратор Google Workspace устанавливает приложение Chat в пространствах прямых сообщений для пользователей в своей организации. Дополнительную информацию о приложениях Chat, установленных администраторами, можно найти в разделе «Установка приложений Marketplace в вашем домене» в справочной документации администратора Google Workspace. | Приложение Chat отправляет вводное сообщение, в котором объясняется, что оно делает и как пользователи в пространстве могут с ним взаимодействовать. |
| Сообщение | Пользователь взаимодействует с приложением Chat в сообщении одним из следующих способов:
| Приложение 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 | |
| |
chat.messagePayload | Полезная нагрузка, которую приложения чата получают от триггера сообщения . |
chat.addedToSpacePayload | Полезная нагрузка, которую приложения чата получают от триггера «Добавлено в пространство» . |
chat.removedFromSpacePayload | Полезная нагрузка, которую приложения чата получают от триггера «Удалено из космоса» . |
chat.buttonClickedPayload | Полезная нагрузка, которую получают приложения чата, когда пользователи нажимают кнопку в сообщении или карточке. Если пользователь нажимает кнопку для отправки информации, объект |
chat.widgetUpdatedPayload | Полезная нагрузка, которую получают приложения чата, когда пользователи вводят текст в меню множественного выбора виджета Объект |
chat.appCommandPayload | Полезные данные, которые получают приложения чата, когда пользователь использует команду из приложения чата. |
Полезная нагрузка
В зависимости от типа взаимодействия событие содержит полезную нагрузку с одним или несколькими ресурсами Chat API.
Полезная нагрузка сообщения
Полезная нагрузка сообщения chat.messagePayload.message object ( Message )
Сообщение чата, вызвавшее событие. chat.messagePayload.space object ( Space )
Пространство чата, в котором пользователь отправил сообщение, вызвавшее приложение чата.
Когда администраторы устанавливают приложения Chat, для поля Добавлен в космическую полезную нагрузку
Добавлено в пространство chat.addedToSpacePayload.space object ( Space )
Пространство чата, в которое пользователь добавил или установил приложение чата.space.adminInstalled установлено значение true . chat.addedToSpacePayload.interactionAdd boolean
Добавляет ли пользователь приложение Chat в пространство с помощью сообщения. Например, @упоминает приложение «Чат» или использует косую черту. Если true , Chat отправляет другой объект события с messagePayload , содержащим информацию о сообщении.
Когда администраторы удаляют приложения Chat, для поля Удалена из космического груза
Удалено из космоса chat.removedFromSpacePayload.space object ( Space )
Пространство чата, из которого пользователь удалил или удалил приложение чата.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.appCommandIdstring ( 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 чата