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

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

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

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

Предпосылки

• Учетная запись Google Workspace Business или Enterprise с доступом к 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. В разделе «Интерактивные функции» просмотрите настройки и выполните обновления в зависимости от функций, которые вы хотите реализовать:

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