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

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

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

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

Создайте приложение интерактивного чата в качестве дополнения к Google Workspace.

Чтобы создать приложение Chat, которое взаимодействует с пользователями Chat, вы можете создать надстройку Google Workspace, расширяющую Chat. Вместо получения событий взаимодействия от Chat API приложение Chat получает и отвечает на дополнительные объекты событий. Дополнительную информацию см. в разделе «Расширение Google Chat» в документации надстройки Google Workspace.

Предварительные условия

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

• HTTP-сервис с облачными функциями Google
• Скрипт Google Apps
• Google Cloud Dialogflow CX
• Google Cloud Pub/Sub

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

/**
 * 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 API, см. раздел Создание сообщения . Руководства по использованию дополнительных методов Chat API см. в обзоре Chat API .

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

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

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

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

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

Создайте приложение интерактивного чата в качестве дополнения к Google Workspace.

Чтобы создать приложение Chat, которое взаимодействует с пользователями Chat, вы можете создать надстройку Google Workspace, расширяющую Chat. Вместо получения событий взаимодействия от Chat API приложение Chat получает и отвечает на дополнительные объекты событий. Дополнительную информацию см. в разделе «Расширение Google Chat» в документации надстройки Google Workspace.

Предварительные условия

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

• HTTP-сервис с облачными функциями Google
• Скрипт Google Apps
• Google Cloud Dialogflow CX
• Google Cloud Pub/Sub

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

/**
 * 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 API, см. раздел Создание сообщения . Руководства по использованию дополнительных методов Chat API см. в обзоре Chat API .

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

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

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

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

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

Создайте приложение интерактивного чата в качестве дополнения к Google Workspace.

Чтобы создать приложение Chat, которое взаимодействует с пользователями Chat, вы можете создать надстройку Google Workspace, расширяющую Chat. Вместо получения событий взаимодействия от Chat API приложение Chat получает и отвечает на дополнительные объекты событий. Дополнительную информацию см. в разделе «Расширение Google Chat» в документации надстройки Google Workspace.

Предварительные условия

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

• HTTP-сервис с облачными функциями Google
• Скрипт Google Apps
• Google Cloud Dialogflow CX
• Google Cloud Pub/Sub

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

/**
 * 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.

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

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

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

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

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

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

Создайте интерактивное приложение чата в качестве надстройки Google Workspace

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

Предварительные условия

Приложение Google Chat, которое включено для интерактивных функций. Чтобы создать интерактивное приложение чата, заполните один из следующих QuickStarts на основе архитектуры приложения , которую вы хотите использовать:

• HTTP Service с функциями Google Cloud
• Google Apps Script
• Google Cloud Dialogflow CX
• Google Cloud Pub/sub

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Обработка http call повлуждает ваш сервис

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

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

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

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

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

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

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

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

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

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

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

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

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

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

/**
 * 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.

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

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

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