将 Google Chat 应用构建为网络钩子

本页介绍了如何设置 webhook，以使用外部触发器将异步消息发送到 Chat 聊天室。例如，您可以配置监控应用，以便在服务器发生故障时通过 Chat 通知值班人员。如需使用 Chat 应用发送同步消息，请参阅发送消息。

采用这种架构设计时，用户无法与该 webhook 或关联的外部应用互动，因为通信是单向的。网络钩子无法进行对话。 它们无法回复或接收用户的消息或 Chat 应用互动事件。如需回复消息，请构建 Chat 应用，而不是 webhook。

虽然在技术上，聊天应用不属于聊天应用（聊天应用使用标准 HTTP 请求连接应用），但为简单起见，本页将其称为聊天应用。每个 webhook 只能在其注册的 Chat 聊天室中运行。传入的 Webhook 可在私信中使用，但前提是所有用户都启用了 Chat 应用。您无法将 webhook 发布到 Google Workspace Marketplace。

下图显示了与 Chat 关联的 webhook 的架构：

在上图中，Chat 应用的信息流如下：

1. Chat 应用逻辑会从外部第三方服务（例如项目管理系统或工单工具）接收信息。
2. Chat 应用逻辑托管在云端或本地系统中，可以使用网络钩子网址向特定 Chat 聊天室发送消息。
3. 用户可以在特定 Chat 聊天室中接收 Chat 应用发送的消息，但无法与 Chat 应用互动。

前提条件

Python

• 拥有对 Google Chat 访问权限的商务版或企业版 Google Workspace 账号。 您的 Google Workspace 组织必须允许用户添加和使用传入的 Webhook。
• Python 3.6 或更高版本
• pip 软件包管理工具

• httplib2 库。如需安装该库，请在命令行界面中运行以下命令：

  pip install httplib2

• Google Chat 聊天室。如需使用 Google Chat API 创建聊天室，请参阅创建聊天室。如需在 Chat 中创建聊天室，请参阅帮助中心文档。

Node.js

• 拥有对 Google Chat 访问权限的商务版或企业版 Google Workspace 账号。 您的 Google Workspace 组织必须允许用户添加和使用传入的 Webhook。
• Node.js 14 或更高版本
• npm 软件包管理工具
• Google Chat 聊天室。如需使用 Google Chat API 创建聊天室，请参阅创建聊天室。如需在 Chat 中创建聊天室，请参阅帮助中心文档。

Java

• 拥有对 Google Chat 访问权限的商务版或企业版 Google Workspace 账号。 您的 Google Workspace 组织必须允许用户添加和使用传入的 Webhook。
• Java 11 或更高版本
• Maven 软件包管理工具
• Google Chat 聊天室。如需使用 Google Chat API 创建聊天室，请参阅创建聊天室。如需在 Chat 中创建聊天室，请参阅帮助中心文档。

Apps 脚本

• 拥有对 Google Chat 访问权限的商务版或企业版 Google Workspace 账号。 您的 Google Workspace 组织必须允许用户添加和使用传入的 Webhook。
• 创建一个独立的 Apps 脚本项目，然后开启高级聊天服务。
• Google Chat 聊天室。如需使用 Google Chat API 创建聊天室，请参阅创建聊天室。如需在 Chat 中创建聊天室，请参阅帮助中心文档。

创建网络钩子

如需创建网络钩子，请在您要接收消息的 Chat 聊天室中注册该网络钩子，然后编写用于发送消息的脚本。

注册传入的 webhook

1. 在浏览器中，打开 Chat。 您无法通过 Chat 移动应用配置网络钩子。
2. 前往您要添加 Webhook 的聊天室。
3. 点击聊天室标题旁边的 展开箭头，然后点击应用和集成。

4. 点击 添加 Webhook。

   注意 ：如果您无法点击该按钮，则表示您的 Google Workspace 组织不允许用户添加或使用 webhook。如需了解详情，请参阅 Google Workspace 管理帮助文档中的允许用户安装 Chat 应用。

5. 在名称字段中，输入 Quickstart Webhook。

6. 在头像网址字段中，输入 https://developers.google.com/chat/images/chat-product-icon.png。

7. 点击保存。

8. 如需复制 Webhook 网址，请点击 更多，然后点击 复制链接。

   警告： 请勿在线分享您的 webhook 网址（例如在公共代码库中），因为这会降低其安全性。

编写 webhook 脚本

示例网络钩子脚本会向注册了网络钩子的聊天室发送消息，方法是向网络钩子网址发送 POST 请求。Chat API 会以 Message 实例进行响应。

选择一种语言，了解如何创建 Webhook 脚本：

Python

1. 在工作目录中，创建一个名为 quickstart.py 的文件。

2. 在 quickstart.py 中，粘贴以下代码：

   python/webhook/quickstart.py

   在 GitHub 上查看
   from json import dumps
   from httplib2 import Http
   
   # Copy the webhook URL from the Chat space where the webhook is registered.
   # The values for SPACE_ID, KEY, and TOKEN are set by Chat, and are included
   # when you copy the webhook URL.
   
   def main():
       """Google Chat incoming webhook quickstart."""
       url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN"
       app_message = {"text": "Hello from a Python script!"}
       message_headers = {"Content-Type": "application/json; charset=UTF-8"}
       http_obj = Http()
       response = http_obj.request(
           uri=url,
           method="POST",
           headers=message_headers,
           body=dumps(app_message),
       )
       print(response)
   
   
   if __name__ == "__main__":
       main()

3. 将 url 变量的值替换为您在注册该网络钩子时复制的网络钩子网址。

Node.js

1. 在工作目录中，创建一个名为 index.js 的文件。

2. 在 index.js 中，粘贴以下代码：

   node/webhook/index.js

   在 GitHub 上查看
   /**
    * Sends asynchronous message to Google Chat
    * @return {Object} response
    */
   async function webhook() {
     const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages"
     const res = await fetch(url, {
       method: "POST",
       headers: {"Content-Type": "application/json; charset=UTF-8"},
       body: JSON.stringify({text: "Hello from a Node script!"})
     });
     return await res.json();
   }
   
   webhook().then(res => console.log(res));

3. 将 url 变量的值替换为您在注册该网络钩子时复制的网络钩子网址。

Java

1. 在工作目录中，创建一个名为 pom.xml 的文件。

2. 在 pom.xml 中，复制并粘贴以下内容：

   java/webhook/pom.xml

   在 GitHub 上查看
   <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
   
     <groupId>com.google.chat.webhook</groupId>
     <artifactId>java-webhook-app</artifactId>
     <version>0.1.0</version>
   
     <name>java-webhook-app</name>
     <url>https://github.com/googleworkspace/google-chat-samples/tree/main/java/webhook</url>
   
     <properties>
       <maven.compiler.target>11</maven.compiler.target>
       <maven.compiler.source>11</maven.compiler.source>
     </properties>
   
     <dependencies>
       <dependency>
           <groupId>com.google.code.gson</groupId>
           <artifactId>gson</artifactId>
           <version>2.9.1</version>
       </dependency>
     </dependencies>
   
     <build>
       <pluginManagement>
         <plugins>
           <plugin>
             <artifactId>maven-compiler-plugin</artifactId>
             <version>3.8.0</version>
           </plugin>
         </plugins>
       </pluginManagement>
     </build>
   </project>

3. 在工作目录中，创建以下目录结构 src/main/java。

4. 在 src/main/java 目录中，创建一个名为 App.java 的文件。

5. 在 App.java 中，粘贴以下代码：

   java/webhook/src/main/java/com/google/chat/webhook/App.java

   在 GitHub 上查看
   import com.google.gson.Gson;
   import java.net.http.HttpClient;
   import java.net.http.HttpRequest;
   import java.net.http.HttpResponse;
   import java.util.Map;
   import java.net.URI;
   
   public class App {
     private static final String URL = "https://chat.googleapis.com/v1/spaces/AAAAGCYeSRY/messages";
     private static final Gson gson = new Gson();
     private static final HttpClient client = HttpClient.newHttpClient();
   
     public static void main(String[] args) throws Exception {
       String message = gson.toJson(Map.of("text", "Hello from Java!"));
   
       HttpRequest request = HttpRequest.newBuilder(URI.create(URL))
         .header("accept", "application/json; charset=UTF-8")
         .POST(HttpRequest.BodyPublishers.ofString(message)).build();
   
       HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
   
       System.out.println(response.body());
     }
   }

6. 将 URL 变量的值替换为您在注册该 webhook 时复制的 webhook 网址。

Apps 脚本

1. 在浏览器中，前往 Apps 脚本。

2. 点击 New Project

3. 粘贴以下代码：

   apps-script/webhook/webhook.gs

   在 GitHub 上查看
   function webhook() {
     const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages"
     const options = {
       "method": "post",
       "headers": {"Content-Type": "application/json; charset=UTF-8"},
       "payload": JSON.stringify({"text": "Hello from Apps Script!"})
     };
     const response = UrlFetchApp.fetch(url, options);
     console.log(response);
   }

4. 将 url 变量的值替换为您在注册该 webhook 时复制的 webhook 网址。

运行 webhook 脚本

在 CLI 中，运行以下脚本：

Python

  python3 quickstart.py

Node.js

  node index.js

Java

  mvn compile exec:java -Dexec.mainClass=App

Apps 脚本

• 点击运行。

当您运行该代码时，该 webhook 会向您注册该 webhook 的聊天室发送消息。

发起或回复消息串

1. 在消息请求正文中指定 spaces.messages.thread.threadKey。根据您是发起还是回复会话，请为 threadKey 使用以下值：

   • 如果要发起会话，请将 threadKey 设置为任意字符串，但记下此值以便回复会话。

   • 如果回复某个会话，请指定在该会话启动时设置的 threadKey。例如，如需对使用 MY-THREAD 的初始消息所在的会话发送回复，请设置 MY-THREAD。

2. 定义在未找到指定 threadKey 时线程的行为：

   • 回复消息串或发起新消息串。将 messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD 参数添加到该网络钩子网址。传递此网址参数会导致 Chat 使用指定的 threadKey 查找现有会话。如果找到了，系统会将消息作为对该会话的回复发布。如果找不到，则消息会启动与该 threadKey 对应的新线程。

   • 回复会话或不执行任何操作。将 messageReplyOption=REPLY_MESSAGE_OR_FAIL 参数添加到网络钩子网址。传递此网址参数会导致 Chat 使用指定的 threadKey 查找现有会话。如果找到了，系统会将消息作为对该会话的回复发布。如果未找到任何匹配项，则不会发送消息。

   如需了解详情，请参阅 messageReplyOption。

以下代码示例会启动或回复消息会话：

Python

python/webhook/thread-reply.py

在 GitHub 上查看

from json import dumps
from httplib2 import Http

# Copy the webhook URL from the Chat space where the webhook is registered.
# The values for SPACE_ID, KEY, and TOKEN are set by Chat, and are included
# when you copy the webhook URL.
#
# Then, append messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD to the
# webhook URL.


def main():
    """Google Chat incoming webhook that starts or replies to a message thread."""
    url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
    app_message = {
        "text": "Hello from a Python script!",
        # To start a thread, set threadKey to an arbitratry string.
        # To reply to a thread, specify that thread's threadKey value.
        "thread": {"threadKey": "THREAD_KEY_VALUE"},
    }
    message_headers = {"Content-Type": "application/json; charset=UTF-8"}
    http_obj = Http()
    response = http_obj.request(
        uri=url,
        method="POST",
        headers=message_headers,
        body=dumps(app_message),
    )
    print(response)


if __name__ == "__main__":
    main()

Node.js

node/webhook/thread-reply.js

在 GitHub 上查看

/**
 * Sends asynchronous message to Google Chat
 * @return {Object} response
 */
async function webhook() {
  const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
  const res = await fetch(url, {
    method: "POST",
    headers: {"Content-Type": "application/json; charset=UTF-8"},
    body: JSON.stringify({
      text: "Hello from a Node script!",
      thread: {threadKey: "THREAD_KEY_VALUE"}
    })
  });
  return await res.json();
}

webhook().then(res => console.log(res));

Apps 脚本

apps-script/webhook/thread-reply.gs

在 GitHub 上查看

function webhook() {
  const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
  const options = {
    "method": "post",
    "headers": {"Content-Type": "application/json; charset=UTF-8"},
    "payload": JSON.stringify({
      "text": "Hello from Apps Script!",
      "thread": {"threadKey": "THREAD_KEY_VALUE"}
    })
  };
  const response = UrlFetchApp.fetch(url, options);
  console.log(response);
}

处理错误

Webhook 请求可能会因各种原因而失败，包括：

• 申请无效。
• 托管 Webhook 的 Webhook 或聊天室被删除。
• 间歇性问题，例如网络连接问题或配额限制。

构建 webhook 时，您应通过以下方式妥善处理错误：

• 记录失败情况。
• 对于基于时间、配额或网络连接的错误，请使用指数退避算法重试请求。
• 不执行任何操作，如果发送 webhook 消息不重要，则适用此方法。

Google Chat API 会将错误作为 google.rpc.Status 返回，其中包含 HTTP 错误 code，用于指示遇到的错误类型：客户端错误 (400 系列) 或服务器错误 (500 系列)。如需查看所有 HTTP 映射，请参阅 google.rpc.Code。

{
    "code": 503,
    "message": "The service is currently unavailable.",
    "status": "UNAVAILABLE"
}

警告： 错误 message 文本不属于 API Surface。消息文本可能会发生变更，恕不另行通知。应用代码不得依赖于错误消息文本，而应在以编程方式处理错误时使用错误 code。

如需了解如何解读 HTTP 状态代码和处理错误，请参阅错误。

限制和注意事项

• 在 Google Chat API 中使用 webhook 创建消息时，响应不包含完整的消息。响应只会填充 name 和 thread.name 字段。
• Webhook 受 spaces.messages.create 每聊天室每 60 秒 60 次的查询限制，该限制会在聊天室中的所有 Chat 应用之间共享。如需详细了解 Chat API 配额，请参阅用量限制。

相关主题

• 选择 Chat 应用架构
• 发送卡片消息
• 设置邮件格式