此页面由 Cloud Translation API 翻译。

接收和响应互动事件

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

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

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

前提条件

拥有 Google Workspace 商务版或企业版账号，且有权访问 Google Chat。
创建 Google Cloud 项目。
配置 OAuth 同意屏幕。
启用 Google Chat API。

互动事件类型

Google Chat 应用互动事件是指用户调用或与 Chat 应用互动的任何操作，例如 @提及 Chat 应用或将其添加到聊天室。

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

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

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

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

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

用户互动	`eventType`	聊天应用的典型回答
用户向 Chat 应用发送消息。例如， @提及 Chat 应用或使用斜杠命令。	`MESSAGE`	聊天应用会根据消息内容做出回答。例如，聊天应用会回复斜杠命令 `/about`，并发送一条消息来解释该聊天应用可以执行的任务。
用户将 Chat 应用添加到聊天室。	`ADDED_TO_SPACE`	Chat 应用会发送一条初始消息，说明其用途以及聊天室中的用户如何与其互动。
用户从聊天室中移除 Chat 应用。	`REMOVED_FROM_SPACE`	Chat 应用会移除为聊天室配置的所有入站通知（例如删除 Webhook），并清理所有内部存储空间。
用户点击 Chat 应用消息、对话框或首页中的卡片上的按钮。	`CARD_CLICKED`	聊天应用会处理并存储用户提交的任何数据，或返回另一张卡片。
用户在 1 对 1 消息中点击首页标签页，打开 Chat 应用的首页。	`APP_HOME`	Chat 应用从首页返回静态或互动卡片。
用户通过 Chat 应用的首页提交表单。	`SUBMIT_FORM`	聊天应用会处理并存储用户提交的任何数据，或返回另一张卡片。
用户使用快捷指令调用命令。	`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 应用发送相关的互动事件：

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

前往“Chat API 配置”页面

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

字段	说明
功能	必需。一组字段，用于确定 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 应用。
命令	可选。Chat 应用的斜杠命令和快速命令。用户可以通过命令请求执行操作或使用 Chat 应用的特定功能。如需了解详情，请参阅响应 Google Chat 应用命令。
链接预览	可选。Chat 应用可以识别并且可以在用户发送链接时为其提供额外内容的网址格式。如需了解详情，请参阅预览链接。
公开范围	可选。最多 5 位个人用户，或一个或多个可以查看和安装您的 Chat 应用的 Google 群组。您可以使用此字段测试您的 Chat 应用，或与您的团队分享该 Chat 应用。如需了解详情，请参阅测试互动功能。

点击保存。保存 Chat 应用配置后，您的 Chat 应用即可供 Google Workspace 组织中的指定用户使用。

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

处理对服务的 HTTP 调用重试

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

处理或响应互动事件

本部分介绍 Google Chat 应用如何处理互动事件并做出响应。

当 Chat 应用收到来自 Google Chat 的互动事件后，可以通过多种方式做出响应。在许多情况下，交互式聊天应用会通过消息回复用户。 Google Chat 应用还可以从数据源中查找某些信息、记录互动事件信息，或执行其他任何操作。这种处理行为从本质上定义了 Google Chat 应用。

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

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

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

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

实时回答

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

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

使用信息回复

在此示例中，每当 Chat 应用被添加到聊天室时，它都会创建并发送一条短信。如需了解有关用户引导的最佳实践，请参阅向用户介绍您的 Chat 应用。

如需在用户将您的 Chat 应用添加到聊天室时发送短信，您的 Chat 应用需要对 ADDED_TO_SPACE interaction 事件做出响应。如需使用短信响应 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 概览。