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

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

Google Chat 应用互动事件表示用户在调用 Chat 应用或与 Chat 应用互动时执行的任何操作,例如用“@”提及 Chat 应用或将其添加到聊天室。当用户与 Chat 应用互动时,Google Chat 会向 Chat 应用发送互动事件。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 应用,请参阅 Chat 应用实现架构

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

  1. 在 Google Cloud 控制台中,打开 Google Chat API 页面:

    前往 Google Chat API 页面

  2. 点击配置标签页。
  3. 互动功能部分,点击启用互动功能开关,将其切换到开启位置。
  4. 功能中,选中以下一个或两个复选框:
    1. 接收 1 对 1 消息:允许用户在私信 (DM) 聊天室中与您的 Chat 应用互动。每当用户在 DM 聊天室中发送消息时,您的 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 客户端库验证您的不记名令牌:

对于在 Google Chat 请求中发送的不记名令牌,颁发者为 chat@system.gserviceaccount.com,并且 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 = "chat@system.gserviceaccount.com";

  // 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 = 'chat@system.gserviceaccount.com'

# 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 应用如何处理和响应互动事件。

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

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

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

用于说明 Google Chat 应用如何处理互动事件的架构。

实时回答

互动事件可让 Chat 应用实时或同步响应。同步响应不需要身份验证

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

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

异步响应

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

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