接收和响应用户互动

本页面介绍了 Google Chat 应用如何接收和响应用户互动（也称为 Google Chat 应用互动事件）。

本页面介绍了如何执行以下操作：

  • 配置 Chat 应用以接收互动事件。
  • 在基础架构上处理互动事件。
  • 在适当的情况下，响应互动事件。

前提条件

启用了交互功能的 Google Chat 应用。如需创建交互式 Chat 应用，请根据您要使用的应用架构完成以下任一快速入门：

互动事件类型

Google Chat 应用互动事件表示用户为调用 Chat 应用或与 Chat 应用互动而执行的任何操作，例如用“@”提及 Chat 应用或将其添加到聊天室。

当用户与 Chat 应用互动时，Google Chat 会向 Chat 应用发送互动事件，该事件在 Chat API 中表示为 Event 类型。Chat 应用可以使用该事件处理互动，并且可以选择性地回复消息。

对于每种类型的用户互动，Google Chat 都会发送不同类型的互动事件，以帮助您的 Chat 应用相应地处理每种事件类型。互动事件类型使用 eventType 对象表示。

例如，当用户将 Chat 应用添加到聊天室时，Google Chat 会针对任何互动使用事件类型 ADDED_TO_SPACE，以便 Chat 应用能够立即在聊天室中回复欢迎消息。

聊天应用发布欢迎消息。
图 1：当用户将 Chat 应用添加到聊天室时，Chat 应用会收到 ADDED_TO_SPACE 互动事件，Chat 应用会处理该互动事件，以在聊天室中发送欢迎消息。

下表显示了常见的用户互动、Chat 应用收到的互动事件类型，以及 Chat 应用通常如何响应：

用户互动 eventType Chat 应用的典型响应
用户通过 @提及或使用斜杠命令来调用 Chat 应用。 MESSAGE Chat 应用会根据消息内容做出响应。例如，Chat 应用在回复 /about 命令时会提供一条消息，说明该 Chat 应用可以执行的任务。
用户将 Chat 应用添加到聊天室。 ADDED_TO_SPACE Chat 应用会发送 新手入门消息，其中会说明其功能以及聊天室中的用户可以如何与之互动。
用户从聊天室中移除 Chat 应用。 REMOVED_FROM_SPACE Chat 应用会移除为聊天室配置的所有传入通知（例如删除 webhook），并清除所有内部存储空间。
用户点击 Chat 应用消息、对话框或首页中卡片上的按钮。 CARD_CLICKED Chat 应用会处理并存储用户提交的所有数据，或者返回其他卡片。
用户点击 1 对 1 消息中的首页标签页，打开 Chat 应用的首页。 APP_HOME Chat 应用会从首页返回静态或互动卡片。
用户从 Chat 应用的首页提交表单。 SUBMIT_FORM Chat 应用会处理和存储用户提交的所有数据，或返回另一张卡片。

如需查看所有受支持的互动事件，请参阅 EventType 参考文档。

来自对话框的互动事件

如果您的 Chat 应用打开对话框，则互动事件包含以下可用于处理响应的额外信息：

  • 将 isDialogEvent 设置为 true。
  • DialogEventType 会说明互动是触发对话框打开、提交对话框中的信息，还是关闭对话框。

下表显示了与对话框的常见互动、相应的对话框事件类型，以及对话应用的典型响应方式说明：

用户与对话框的互动 对话框事件类型 典型回复
用户触发对话请求。例如，他们使用正斜线命令或点击消息中的按钮。 REQUEST_DIALOG Chat 应用会打开对话框。
用户通过点击按钮在对话框中提交信息。 SUBMIT_DIALOG Chat 应用会导航到另一个对话框或关闭对话框以完成互动。
用户在提交信息之前退出或关闭对话框。 CANCEL_DIALOG （可选）Chat 应用可以用新消息进行响应，或者更新用户用来打开对话框的消息或卡片。

如需了解详情，请参阅打开交互式对话框。

接收 Chat 应用互动事件

本部分介绍了如何接收和处理 Chat 应用的互动事件。

将您的 Chat 应用配置为接收互动事件

并非所有 Chat 应用都是互动式应用。例如，接入 Webhook 只能发送出站消息，无法回复用户。如果您要构建交互式 Chat 应用，则必须选择一个端点，使您的 Chat 应用可以接收、处理和响应互动事件。如需详细了解如何设计您的 Chat 应用，请参阅 Chat 应用实现架构。

对于您要构建的每项互动功能，您都必须在 Chat API 中更新配置，以便 Google Chat 可以向您的 Chat 应用发送相关互动事件：

  1. 在 Google Cloud 控制台中，前往 Chat API 页面，然后点击配置页面：

    前往“Chat API 配置”页面

  2. 在互动功能下，查看设置并根据您要构建的功能进行更新：

    字段 说明
    功能 必需。一组字段，用于确定 Chat 应用如何与用户互动：
    • 接收一对一消息：用户可以直接在 Google Chat 中找到 Chat 应用并向其发送消息。
    • 加入聊天室和群组对话：用户可以将 Chat 应用添加到聊天室和群组对话。
    连接设置 必需。Chat 应用的端点，即以下之一：
    • HTTP 端点网址：托管 Chat 应用实现的 HTTPS 端点。
    • Apps 脚本：实现 Chat 应用的 Apps 脚本项目的部署 ID。
    • Cloud Pub/Sub 主题名称：Chat 应用订阅为端点的 Pub/Sub 主题。
    • Dialogflow：使用 Dialogflow 集成注册 Chat 应用。如需了解详情，请参阅构建能够理解自然语言的 Dialogflow Google Chat 应用。
    斜杠命令 可选。可在 Google Chat 中向用户显示的命令。让用户能够在 Google Chat 中查看 Chat 应用的核心操作，并选择他们想要与之互动的特定操作。有关详情，请参阅以 Chat 应用的身份响应斜杠命令。
    链接预览 可选。Chat 应用可在用户发送链接时识别并提供额外内容的网址格式。如需了解详情，请参阅预览链接。
    公开范围 可选。最多 5 位个人或 1 个或多个 Google 群组，他们可以查看和安装您的 Chat 应用。您可以使用此字段测试 Chat 应用，或与团队共享 Chat 应用。如需了解详情，请参阅测试交互式功能。

  3. 点击保存。保存 Chat 应用配置后，您的 Chat 应用将面向 Google Workspace 组织中的指定用户提供。

您的 Chat 应用现已配置为接收来自 Google Chat 的互动事件。

处理对服务的 HTTP 调用重试

如果向您的服务发出的 HTTPS 请求失败（例如超时、临时网络故障或非 2xx 的 HTTPS 状态代码），Google Chat 可能会在几分钟内重试传送几次（但不能保证）。因此，在某些情况下，聊天应用可能会多次收到同一消息。如果请求成功完成但返回无效的消息载荷，Google Chat 不会重试该请求。

处理或响应互动事件

本部分介绍了 Google Chat 应用如何处理和响应互动事件。

在您的 Chat 应用收到来自 Google Chat 的互动事件后，它们可以通过多种方式进行响应。在许多情况下，交互式聊天应用会通过消息回复用户。Google Chat 应用还可以从数据源查询一些信息，记录互动事件信息等。 这种处理行为在本质上定义了 Google Chat 应用。

如需同步响应，Chat 应用必须在 30 秒内做出响应，并且响应必须发布在发生互动的聊天室中。否则，Chat 应用可以异步响应。

对于每个互动事件，Chat 应用都会收到请求正文，这是代表事件的 JSON 载荷。您可以使用这些信息来处理响应。如需查看事件载荷示例，请参阅Chat 应用互动事件类型。

下图演示了 Google Chat 应用通常如何处理或响应不同类型的互动事件：

Google Chat 应用处理互动事件的架构。

实时回答

借助互动事件，聊天应用可以实时或同步响应。同步响应不需要进行身份验证。

如需实时响应，Chat 应用必须返回 Message 对象。如需在聊天室中用消息回复，Message 对象可以包含 text、cardsV2 和 accessoryWidgets 对象。如需与其他类型的回答搭配使用，请参阅以下指南：

使用信息回复

在此示例中，您的 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`.'
    });
  }
};

Apps 脚本

/**
 * 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 应用可以通过调用 Google Chat API 进行异步响应。

如需使用 Chat API 创建消息，请参阅创建消息。如需有关使用其他 Chat API 方法的指南，请参阅 Chat API 概览。