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

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

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

На этой странице описано, как:

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

Требования

Аккаунт Google Workspace версии Business или Enterprise с доступом к Google Chat.
Создайте проект Google Cloud.
Настройте окно запроса доступа OAuth.
Включите Google Chat API.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Подробнее о том, как открыть интерактивные диалоговые окна…

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

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

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

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

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

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

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

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

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

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

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

Как настроить начальные запросы

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

Чтобы добавить и настроить стартовые запросы:

В консоли Google Cloud перейдите на страницу Configuration (Конфигурация) Chat API:

Перейти на страницу конфигурации Chat API
В разделе Интерактивные функции найдите Подсказки для начала и нажмите Добавить подсказку.
В поле Ранг (1–3) введите число от 1 до 3, чтобы задать порядок показа.
В разделе Выбор типа укажите, как будет работать запрос:
- Текстовый запрос: При нажатии на чип запроса в поле чата появляется заданный текст.
- Командная строка: При нажатии выполняется зарегистрированная слеш-команда или быстрая команда. Команды, требующие дополнительных аргументов, выбрать нельзя.
Настройте запрос в зависимости от выбранного типа:
- Если вы выбрали текстовый запрос:
  1. В поле Заголовок введите заголовок подсказки, который будет показываться на чипе (до 30 символов).
  2. В поле Текст запроса введите текст, который будет отображаться на панели создания письма (до 60 символов).
  3. Вы можете добавить локализованные названия и текст для пользователей, говорящих на других языках:
  4. В разделе Локализованные подсказки нажмите Добавить язык.
  5. В разделе Язык выберите поддерживаемый язык из раскрывающегося списка.
  6. В поле Локализованное название введите название на нужном языке (до 30 символов).
  7. В поле Локализованный текст запроса введите текст запроса на нужном языке (до 60 символов).
  8. Повторите эти действия, чтобы добавить другие языки.
- Если вы выбрали "Командная строка":
  1. В разделе Слеш-команда / Быстрая команда выберите команду из раскрывающегося списка.
Нажмите Готово, а затем Сохранить внизу страницы.

Обрабатывайте повторные вызовы 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 обычно обрабатывает или реагирует на различные типы событий взаимодействия:

Архитектура обработки событий взаимодействия в приложениях Google Chat.

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

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

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

Отправить в ответ сообщение

В этом примере приложение Chat создает и отправляет текстовое сообщение каждый раз, когда его добавляют в чат-группу. Рекомендации по знакомству пользователей с приложением 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.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // 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`.'
    });
  }
};

Python

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      '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`.'
    })
  return json.jsonify({})

Java

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return new Message().setText(
          "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`.");
      default:
        return new Message();
    }
  }
}

Apps Script

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