接收和回复用户与您的 Google Chat 应用互动的内容

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

Google Chat 应用互动事件表示用户在调用 Chat 应用或与 Chat 应用互动时执行的任何操作，例如用“@”提及 Chat 应用或将其添加到聊天室。当用户与 Chat 应用互动时，Google Chat 会向 Chat 应用发送互动事件。Chat 应用可以使用该事件来处理互动并创建响应。

例如，Chat 应用可通过互动事件执行以下任一操作：

互动事件示例	聊天应用的典型响应
用户通过用“@”提及该应用或使用斜杠命令来调用该应用。	Chat 应用会处理消息内容以创建一条消息。例如，Chat 应用会回复 /about 命令并提供一条消息，说明 Chat 应用可以执行的任务。
用户将 Chat 应用添加到聊天室。	该 Chat 应用会发送一条新手入门消息，说明该应用的用途以及聊天室中的用户可以如何与之互动。
用户从聊天室中移除了 Chat 应用。	Chat 应用会移除为聊天室配置的所有传入通知（例如删除网络钩子），并清理所有内部存储空间。
用户点击 Chat 应用发送的卡片或对话框上的按钮。	Chat 应用会处理和存储用户提交的所有数据，或返回其他卡片或对话框。

对于每种类型的用户互动，Google Chat 都会发送不同类型的互动事件。例如，Google Chat 会在用户在消息中调用 Chat 应用的任何互动时使用事件类型 MESSAGE。如需了解详情，请参阅 Google Chat 应用互动事件类型。

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

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

接收 Chat 应用互动事件

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

配置 Chat 应用以接收互动事件

并非所有聊天应用都是交互式应用。例如，传入的网络钩子只能发送传出消息，无法回复用户。构建交互式 Chat 应用时，您必须选择一个端点，以便 Chat 应用能够接收、处理和响应互动事件。如需详细了解如何设计 Chat 应用，请参阅 Chat 应用实现架构。

如果您构建了交互式聊天应用，则必须配置 Google Chat API，以便 Google Chat 可以向您发送互动事件：

1. 在 Google Cloud 控制台中，打开 Google Chat API 页面：

   前往 Google Chat API 页面

2. 点击配置标签页。
3. 在互动功能部分，点击启用互动功能，将其切换到开启位置。
4. 在功能中，选中以下一个或两个复选框：
   1. 接收 1 对 1 消息：允许用户在私信 (DM) 聊天室中与您的 Chat 应用互动。每当用户在私信聊天室中发送消息时，您的 Chat 应用就会收到互动事件。
   2. 加入聊天室和群组对话：允许用户在有多人的聊天室中添加和移除您的 Chat 应用。每当在聊天室中添加或移除您的应用时，以及每当用户在聊天室中用“@”提及或在聊天室中使用斜杠命令时，您的 Chat 应用都会收到互动事件。
5. 在连接设置中，指定 Google Chat 将 Chat 应用互动事件发送到何处。
6. 可选：在 Slash 命令中，添加并配置一个或多个斜杠命令。如需了解详情，请参阅设置斜杠命令。
7. 可选：在链接预览中，添加并配置您的 Chat 应用预览的一种或多种网址格式。如需了解详情，请参阅预览链接。
8. 点击保存。

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

对来自 Google Chat 的请求进行身份验证

对于基于 HTTP 端点构建的应用，本部分介绍如何验证对端点的请求是否来自 Google Chat。

为了将互动事件分派到您的 Chat 应用的端点，Google 会向您的服务发出请求。为了验证请求是否来自 Google，Google Chat 会在发送到端点的每个 HTTPS 请求的 Authorization 标头中添加不记名令牌。例如：

POST
Host: yourappurl.com
Authorization: Bearer AbCdEf123456
Content-Type: application/json
User-Agent: Google-Dynamite

上例中的字符串 AbCdEf123456 是不记名授权令牌。这是 Google 生成的加密令牌。您可以使用开源 Google API 客户端库验证您的不记名令牌：

• Java：https://github.com/google/google-api-java-client
• Python：https://github.com/google/google-api-python-client
• .NET：https://github.com/google/google-api-dotnet-client

对于在 Google Chat 请求中发送的不记名令牌，颁发者为 [e-mail]，并且 audience 字段设置为您用于构建 Chat 应用的 Google Cloud 项目的编号。例如，如果您的 Chat 应用的 Cloud 项目编号为 1234567890，则不记名令牌中的 audience 字段为 1234567890。

如果令牌未通过 Chat 应用的验证，您的服务应使用 HTTPS 响应代码 401 (Unauthorized) 来响应请求。

Java

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.Collections;

import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier;
import com.google.api.client.googleapis.auth.oauth2.GooglePublicKeysManager;
import com.google.api.client.http.apache.ApacheHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;

/** Tool for verifying JWT Tokens for Apps in Google Chat. */
public class JWTVerify {
  // Bearer Tokens received by apps will always specify this issuer.
  static String CHAT_ISSUER = "[e-mail]";

  // Url to obtain the public certificate for the issuer.
  static String PUBLIC_CERT_URL_PREFIX =
      "https://www.googleapis.com/service_accounts/v1/metadata/x509/";

  // Intended audience of the token, which is the project number of the app.
  static String AUDIENCE = "1234567890";

  // Get this value from the request's Authorization HTTPS header.
  // For example, for "Authorization: Bearer AbCdEf123456" use "AbCdEf123456"
  static String BEARER_TOKEN = "AbCdEf123456";

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    JsonFactory factory = new JacksonFactory();

    GooglePublicKeysManager.Builder keyManagerBuilder =
        new GooglePublicKeysManager.Builder(new ApacheHttpTransport(), factory);

    String certUrl = PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER;
    keyManagerBuilder.setPublicCertsEncodedUrl(certUrl);

    GoogleIdTokenVerifier.Builder verifierBuilder =
        new GoogleIdTokenVerifier.Builder(keyManagerBuilder.build());
    verifierBuilder.setIssuer(CHAT_ISSUER);
    GoogleIdTokenVerifier verifier = verifierBuilder.build();

    GoogleIdToken idToken = GoogleIdToken.parse(factory, BEARER_TOKEN);
    if (idToken == null) {
      System.out.println("Token cannot be parsed");
      System.exit(-1);
    }

    // Verify valid token, signed by CHAT_ISSUER.
    if (!verifier.verify(idToken)
        || !idToken.verifyAudience(Collections.singletonList(AUDIENCE))
        || !idToken.verifyIssuer(CHAT_ISSUER)) {
      System.out.println("Invalid token");
      System.exit(-1);
    }

    // Token originates from Google and is targeted to a specific client.
    System.out.println("The token is valid");
  }
}

Python

import sys

from oauth2client import client

# Bearer Tokens received by apps will always specify this issuer.
CHAT_ISSUER = '[e-mail]'

# Url to obtain the public certificate for the issuer.
PUBLIC_CERT_URL_PREFIX = 'https://www.googleapis.com/service_accounts/v1/metadata/x509/'

# Intended audience of the token, which will be the project number of the app.
AUDIENCE = '1234567890'

# Get this value from the request's Authorization HTTPS header.
# For example, for 'Authorization: Bearer AbCdEf123456' use 'AbCdEf123456'.
BEARER_TOKEN = 'AbCdEf123456'

try:
  # Verify valid token, signed by CHAT_ISSUER, intended for a third party.
  token = client.verify_id_token(
      BEARER_TOKEN, AUDIENCE, cert_uri=PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER)

  if token['iss'] != CHAT_ISSUER:
    sys.exit('Invalid issuee')
except:
  sys.exit('Invalid token')

# Token originates from Google and is targeted to a specific client.
print 'The token is valid'

处理对服务的 HTTP 调用重试

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

处理或响应互动事件

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

从 Google Chat 收到互动事件后，您的 Chat 应用可以通过多种方式进行响应。在许多情况下，交互式 Chat 应用会使用消息来回复用户。Google Chat 应用还可以从数据源查询某些信息、记录互动事件信息或其他任何内容。这种处理行为本质上就是 Google Chat 应用的定义。

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

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

实时响应

互动事件允许 Chat 应用实时或同步响应。同步响应不需要进行身份验证。

如需创建对互动事件的同步响应，请参阅以下指南：

• 创建卡片消息
• 创建短信
• 打开交互式对话框
• 预览链接
• 读取用户在卡片上输入的表单数据
• 设置斜杠命令

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

异步响应

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

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