接收和响应互动事件

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

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

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

前提条件

• 拥有 Google Chat访问权限的 Business 或 Enterprise Google Workspace账号。
• 创建 Google Cloud 项目。
• 配置 OAuth 权限请求页面。
• 启用 Google Chat API。

互动事件的类型

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

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

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

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

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

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

来自对话框的互动事件

如果 Chat 应用打开 对话框，互动事件会包含以下 额外信息，您可以使用这些信息来处理响应：

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

下表显示了与对话框的常见互动、相应的对话框事件类型，以及 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 应用。如需了解详情，请参阅构建可理解自然语言的 DialogflowGoogle Chat 应用。
   命令	可选。Chat 应用的斜杠命令和快速命令。借助命令，用户可以请求操作或使用 Chat 应用的特定功能。如需了解详情，请参阅 响应 Google Chat 应用命令。
   链接预览	可选。Chat 应用可以识别并且可以在用户发送链接时为其提供额外内容的网址格式。如需了解详情，请参阅预览链接。
   公开范围	可选。最多 5 位个人用户，或一个或多个可以查看和安装 Chat 应用的 Google 群组。使用此字段测试 Chat 应用，或与团队共享 Chat 应用。如需了解详情，请参阅测试互动功能。

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

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

处理对服务的 HTTP 调用重试

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

处理或响应互动事件

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

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

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

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

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

实时回答

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

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

• 打开互动式对话框
• 预览链接
• 处理用户提交的信息

使用信息回复

在此示例中，每当 Chat 应用添加到聊天室时，它都会创建并发送一条文本消息。如需了解新用户入门的最佳实践，请参阅 向用户介绍 Chat 应用。

如需在用户将 Chat 应用 添加到聊天室时发送文本消息，Chat 应用 会响应 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`.'
  }
}

该代码示例会返回以下文本消息：

异步响应

有时，Chat 应用必须在 30 秒后响应互动事件，或在生成互动事件的聊天室之外执行任务。例如，Chat 应用可能需要在完成长时间运行的任务后响应用户。在这种情况下，Chat 应用可以通过调用 Google Chat API 来异步响应。

如需使用 Chat API 创建消息，请参阅 创建消息。如需了解如何使用 其他 Chat API 方法，请参阅 Chat API 概览。

相关主题

• 发送消息
• 打开互动式对话框
• 预览链接
• 读取用户在卡片上输入的表单数据
• 响应命令
• 为 Chat 应用构建首页
• 验证来自 Chat 的请求
• 测试 Google Chat 应用的互动功能