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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Если 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.
 */
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`.'
    });
  }
};

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({})

@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();
    }
  }
}

/**
 * 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`.'
  }
}

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

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

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

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

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

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