Получать и отвечать на действия пользователей

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

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

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

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

Предпосылки

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

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

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

Когда пользователи взаимодействуют с приложением Chat, Google Chat отправляет приложению 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. Например, @упоминает приложение Chat или использует команду с косой чертой.	MESSAGE	Приложение Chat отвечает на основе содержания сообщения. Например, приложение Chat отвечает на команду с косой чертой /about сообщением, в котором объясняются задачи, которые может выполнять приложение Chat.
Пользователь добавляет приложение чата в пространство.	ADDED_TO_SPACE	Приложение Chat отправляет приветственное сообщение , в котором объясняется, что оно делает и как пользователи могут с ним взаимодействовать.
Пользователь удаляет приложение чата из пространства.	REMOVED_FROM_SPACE	Приложение Chat удаляет все входящие уведомления, настроенные для этого пространства (например, удаление вебхука ), и очищает внутреннюю память.
Пользователь нажимает кнопку на карточке в сообщении, диалоговом окне или на домашней странице приложения Chat.	CARD_CLICKED	Приложение Chat либо обрабатывает и сохраняет все данные, отправленные пользователем, либо возвращает другую карту.
Пользователь открывает домашнюю страницу приложения «Чат», нажимая на вкладку « Главная » в личном сообщении.	APP_HOME	Приложение «Чат» возвращает статическую или интерактивную карточку с главной страницы.
Пользователь отправляет форму с главной страницы приложения Chat.	SUBMIT_FORM	Приложение Chat либо обрабатывает и сохраняет все данные, отправленные пользователем, либо возвращает другую карту.
Пользователь вызывает команду с помощью быстрой команды.	APP_COMMAND	Приложение Chat отвечает на основе вызванной команды. Например, приложение Chat отвечает на команду About сообщением, в котором объясняются задачи, которые может выполнять приложение Chat.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   Поле	Описание
   Функциональность	Обязательно. Набор полей, определяющих, как приложение Chat может взаимодействовать с пользователями: Получайте сообщения 1:1 : пользователи могут находить приложение 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 или для того, чтобы поделиться приложением Chat с вашей командой. Для получения дополнительной информации см. Тестирование интерактивных функций .

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

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

Обработка повторных HTTP-вызовов к вашему сервису

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

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

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

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

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

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

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

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

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

Чтобы ответить в реальном времени, приложение 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`.'
  }
}

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

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

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

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

Похожие темы

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