接收和响应用户互动

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

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

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

构建交互式 Chat 应用作为 Google Workspace 插件

如需构建可与 Chat 用户互动的 Chat 应用，您可以构建扩展 Chat 功能的 Google Workspace 插件。Chat 应用会接收和响应插件事件对象，而不是从 Chat API 接收互动事件。如需了解详情，请参阅 Google Workspace 插件文档中的扩展 Google Chat。

前提条件

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

互动事件类型

Google 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 应用会处理该事件，以便在聊天室中发送欢迎消息。

下表显示了常见的用户互动、聊天应用收到的互动事件类型，以及聊天应用的典型响应方式：

用户互动 eventType Chat 应用的典型响应
用户通过 @提及或使用斜杠命令来调用 Chat 应用。 MESSAGE Chat 应用会根据消息内容做出响应。例如，聊天应用会使用一条消息回复 /about 命令，说明聊天应用可以执行的任务。
用户将 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 应用会处理和存储用户提交的所有数据，或返回另一张卡片。
用户使用快捷命令调用命令。 APP_COMMAND Chat 应用会根据调用的命令做出响应。例如，聊天应用会对 About 命令做出回复，并发送一条消息来说明该聊天应用可以执行哪些任务。

如需查看所有受支持的互动事件，请参阅 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 应用响应正斜线命令。
    链接预览 可选。聊天应用可以识别并且可以在用户发送链接时为其提供额外内容的网址格式。如需了解详情，请参阅预览链接。
    公开范围 可选。最多 5 位个人或一个或多个 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 概览。