Получать и реагировать на события взаимодействия

На этой странице описывается, как ваше приложение Google Chat может получать и реагировать на взаимодействия с пользователем, также известные как события взаимодействия с приложением Google Chat .

На этой странице описывается, как сделать следующее:

• Настройте приложение чата для получения событий взаимодействия.
• Обработайте событие взаимодействия на вашей инфраструктуре.
• При необходимости реагируйте на события взаимодействия.

Примечание: В этом руководстве объясняется, как создать интерактивное приложение чата с использованием событий взаимодействия API чата . Вы также можете создать своё приложение чата как дополнение к Google Workspace. Чтобы узнать, какой фреймворк использовать, см. статью Создание интерактивного приложения Google Chat .

Предпосылки

• Учетная запись Google Workspace Business или Enterprise с доступом к Google Chat .
• Создайте проект Google Cloud .
• Настройте экран согласия OAuth .
• Включить API Google Chat .

Типы событий взаимодействия

Событие взаимодействия с приложением Google Chat представляет собой любое действие, предпринимаемое пользователем для вызова или взаимодействия с приложением Chat, например @упоминание приложения Chat или добавление его в пространство.

Когда пользователи взаимодействуют с приложением Chat, Google Chat отправляет ему событие взаимодействия, представленное как тип Event в API Chat. Приложение Chat может использовать это событие для обработки взаимодействия и, при необходимости, ответить сообщением.

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

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

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

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

Взаимодействие с пользователем	eventType	Типичный ответ чат-приложения
Пользователь отправляет сообщение в приложение Chat. Например, @упоминает приложение Chat или использует команду с косой чертой.	MESSAGE	Приложение Chat реагирует на основе содержания сообщения. Например, на команду /about приложение Chat отвечает сообщением с описанием задач, которые оно может выполнять.
Пользователь добавляет приложение чата в пространство.	ADDED_TO_SPACE	Приложение Chat отправляет приветственное сообщение , в котором объясняется, что оно делает и как пользователи могут с ним взаимодействовать.
Пользователь удаляет приложение чата из пространства.	REMOVED_FROM_SPACE	Приложение «Чат» удаляет все входящие уведомления, настроенные для этого пространства (например, удаление веб-перехватчика ), и очищает внутреннюю память.
Пользователь нажимает кнопку на карточке в сообщении, диалоге или на домашней странице приложения чата.	CARD_CLICKED	Приложение Chat либо обрабатывает и сохраняет все данные, отправленные пользователем, либо возвращает другую карту.
Пользователь открывает домашнюю страницу приложения «Чат», нажимая на вкладку « Главная » в личном сообщении.	APP_HOME	Приложение «Чат» возвращает статическую или интерактивную карточку с главной страницы.
Пользователь отправляет форму с главной страницы приложения Chat.	SUBMIT_FORM	Приложение Chat либо обрабатывает и сохраняет все данные, отправленные пользователем, либо возвращает другую карту.
Пользователь вызывает команду с помощью быстрой команды.	APP_COMMAND	Приложение Chat реагирует на вызванную команду. Например, на команду «О программе» приложение Chat отвечает сообщением с описанием задач, которые может выполнять приложение Chat.

Чтобы просмотреть все поддерживаемые события взаимодействия, см. справочную документацию EventType .

События взаимодействия из диалогов

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

• isDialogEvent имеет значение true .
• DialogEventType уточняет, приводит ли взаимодействие к открытию диалогового окна, отправке информации из диалогового окна или закрытию диалогового окна.

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

Взаимодействие пользователя с диалогом	Тип события диалога	Типичный ответ
Пользователь инициирует диалоговый запрос. Например, он использует команду с косой чертой или нажимает кнопку в сообщении.	REQUEST_DIALOG	Приложение «Чат» открывает диалог.
Пользователь отправляет информацию в диалоговом окне, нажимая кнопку.	SUBMIT_DIALOG	Приложение чата либо переходит к другому диалоговому окну, либо закрывает диалоговое окно, чтобы завершить взаимодействие.
Пользователь выходит или закрывает диалоговое окно перед отправкой информации.	CANCEL_DIALOG	При желании приложение чата может ответить новым сообщением или обновить сообщение или карточку, с которой пользователь открыл диалог.

Для получения дополнительной информации см. раздел Открытие интерактивных диалогов .

Получать события взаимодействия с приложением чата

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

Настройте приложение чата для получения событий взаимодействия

Не все приложения Chat интерактивны. Например, входящие веб-перехватчики могут только отправлять исходящие сообщения и не могут отвечать пользователям. Если вы разрабатываете интерактивное приложение Chat, необходимо выбрать конечную точку, которая позволит вашему приложению Chat получать, обрабатывать и реагировать на события взаимодействия. Подробнее о разработке приложения Chat см. в статье «Архитектуры реализации приложений Chat» .

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

1. В консоли Google Cloud перейдите на страницу Chat API и нажмите страницу Configuration :

   Перейти на страницу конфигурации API чата

2. В разделе «Интерактивные функции» просмотрите настройки и выполните обновления в зависимости от функций, которые вы хотите реализовать:

   Поле	Описание
   Функциональность	Обязательно. Набор полей, определяющих, как приложение Chat взаимодействует с пользователями. По умолчанию пользователи могут находить приложение Chat и отправлять ему сообщения непосредственно в Google Chat. Присоединяйтесь к пространствам и групповым беседам : пользователи могут добавлять приложение Chat в пространства и групповые беседы.
   Настройки подключения	Обязательно. Конечная точка для приложения «Чат», которая может быть одной из следующих: URL конечной точки HTTP : конечная точка HTTPS, на которой размещена реализация приложения чата. Apps Script : идентификатор развертывания для проекта Apps Script, реализующего приложение чата. Имя темы Cloud Pub/Sub : тема Pub/Sub, на которую приложение Chat подписывается как на конечную точку. Dialogflow : регистрирует приложение Chat с интеграцией Dialogflow. Подробнее см. в статье «Создание приложения DialogflowGoogle Chat, распознающего естественный язык» .
   Команды	Необязательно. Слэш-команды и быстрые команды для приложения Chat. Команды позволяют пользователям запрашивать действие или использовать определённую функцию вашего приложения Chat. Подробнее см. в разделе Ответ на команды приложения Google Chat .
   Предварительные просмотры ссылок	Необязательно. Шаблоны URL, которые приложение Chat распознаёт и предоставляет дополнительный контент при отправке ссылок пользователями. Подробнее см. в разделе Предварительный просмотр ссылок .
   Видимость	Необязательно. До пяти пользователей или одна или несколько групп Google, которые могут просматривать и устанавливать ваше приложение Chat. Используйте это поле для тестирования приложения Chat или для того, чтобы поделиться им с вашей командой. Подробнее см. в разделе Тестирование интерактивных функций .

3. Нажмите «Сохранить» . После сохранения конфигурации приложения «Чат» оно станет доступно указанным пользователям в вашей организации Google Workspace.

Ваше приложение Chat теперь настроено на получение событий взаимодействия из Google Chat.

Обработка повторных HTTP-вызовов к вашей службе

Если HTTPS-запрос к вашему сервису не выполняется (например, из-за тайм-аута, временного сбоя сети или кода статуса HTTPS, отличного от 2xx), Google Chat может повторить попытку доставки несколько раз в течение нескольких минут (но это не гарантируется). В результате в определённых ситуациях приложение Chat может получать одно и то же сообщение несколько раз. Если запрос выполнен успешно, но возвращает недопустимые данные, Google Chat не повторяет запрос.

Обрабатывать или реагировать на события взаимодействия

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

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

Для синхронного ответа чат-приложение должно отвечать в течение 30 секунд, а ответ должен быть опубликован в том же месте, где произошло взаимодействие. В противном случае чат-приложение может отвечать асинхронно.

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

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

Отвечайте в режиме реального времени

События взаимодействия позволяют приложениям чата отвечать в режиме реального времени или синхронно . Синхронные ответы не требуют аутентификации .

Для ответа в режиме реального времени приложение чата должно возвращать объект Message . Чтобы ответить сообщением в чате, объект Message может содержать объекты text , cardsV2 и accessoryWidgets . Чтобы использовать его с другими типами ответов, см. следующие руководства:

• Открытые интерактивные диалоги
• Ссылки для предварительного просмотра
• Обработка информации, предоставленной пользователями

Примечание: для событий взаимодействия REMOVED_FROM_SPACE приложения чата не могут отвечать объектом Message , поскольку они больше не находятся в пространстве.

Ответить сообщением

В этом примере ваше приложение Chat создаёт и отправляет текстовое сообщение при каждом добавлении в чат. Чтобы узнать о рекомендациях по адаптации пользователей, см. статью «Познакомьте пользователей с вашим приложением Chat» .

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

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar
      from Google Chat. Take a look at your schedule today by typing
      `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
      learn what else I can do, type `/help`.'
    });
  }
};

Скрипт приложений

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
function onAddToSpace(event) {

  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar
    from Google Chat. Take a look at your schedule today by typing
    `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
    what else I can do, type `/help`.'
  }
}

Пример кода возвращает следующее текстовое сообщение:

Отвечайте асинхронно

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

Чтобы создать сообщение с помощью Chat API, см. раздел Создание сообщения . Инструкции по использованию дополнительных методов Chat API см. в разделе Обзор Chat API .

Похожие темы

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