Tạo ứng dụng Google Chat làm webhook

Trang này mô tả cách thiết lập webhook để gửi tin nhắn không đồng bộ đến phòng Chat bằng các điều kiện kích hoạt bên ngoài. Ví dụ: bạn có thể định cấu hình một ứng dụng giám sát để thông báo cho nhân viên trực tiếp trên Chat khi máy chủ ngừng hoạt động. Để gửi tin nhắn đồng bộ bằng một ứng dụng Chat, hãy xem phần Gửi tin nhắn.

Với loại thiết kế cấu trúc này, người dùng không thể tương tác với webhook hoặc ứng dụng bên ngoài được kết nối vì hoạt động giao tiếp là một chiều. Webhook không mang tính trò chuyện. Họ sẽ không thể trả lời hoặc nhận tin nhắn từ người dùng hoặc các sự kiện tương tác với ứng dụng Chat. Để trả lời tin nhắn, hãy tạo ứng dụng Chat thay vì webhook.

Mặc dù về mặt kỹ thuật, webhook không phải là ứng dụng Chat – webhook kết nối các ứng dụng bằng yêu cầu HTTP thông thường, nhưng trang này gọi webhook là một ứng dụng Chat để đơn giản hoá. Mỗi webhook chỉ hoạt động trong phòng Chat nơi mà nó được đăng ký. Webhook đến chỉ hoạt động trong tin nhắn trực tiếp, nhưng chỉ khi tất cả người dùng đều bật các ứng dụng trong Chat. Bạn không thể xuất bản webhook lên Google Workspace Marketplace.

Sơ đồ dưới đây cho thấy cấu trúc của một webhook được kết nối với Chat:

Cấu trúc của các webhook đến để gửi tin nhắn không đồng bộ đến Chat.

Trong sơ đồ trước, ứng dụng Chat có luồng thông tin sau:

  1. Logic của ứng dụng Chat nhận thông tin từ các dịch vụ bên ngoài của bên thứ ba, chẳng hạn như hệ thống quản lý dự án hoặc công cụ bán vé.
  2. Logic của ứng dụng Chat được lưu trữ trong một hệ thống trên đám mây hoặc tại cơ sở hạ tầng riêng. Những hệ thống này có thể gửi tin nhắn bằng cách sử dụng một URL webhook đến một phòng Chat cụ thể.
  3. Người dùng có thể nhận tin nhắn từ ứng dụng Chat trong phòng Chat cụ thể đó, nhưng không thể tương tác với ứng dụng Chat.

Điều kiện tiên quyết

Python

  • Một tài khoản Google Workspace có quyền truy cập vào Chat. Tổ chức Google Workspace của bạn phải cho phép người dùng thêm và sử dụng webhook đến.
  • Python 3.10.7 trở lên.
  • Thư viện httplib2. Nếu cần, hãy chạy lệnh giao diện dòng lệnh (CLI) sau đây để cài đặt thư viện bằng pip:

    pip install httplib2
    
  • Hiện có phòng Chat.

Node.js

Java

Apps Script

Tạo webhook

Để tạo một webhook, hãy đăng ký webhook trong phòng Chat mà bạn muốn nhận tin nhắn, rồi viết một tập lệnh để gửi tin nhắn.

Đăng ký webhook đến

  1. Trên trình duyệt, hãy mở ứng dụng Chat. Bạn không thể định cấu hình webhook bằng ứng dụng Chat dành cho thiết bị di động.
  2. Chuyển đến không gian mà bạn muốn thêm webhook.
  3. Bên cạnh tên không gian, hãy nhấp vào biểu tượng mũi tên mở rộng thêm, sau đó nhấp vào Ứng dụng và công cụ tích hợp.
  4. Nhấp vào Thêm webhook.

  5. Trong trường Name (Tên), hãy nhập Quickstart Webhook.

  6. Trong trường URL hình đại diện, hãy nhập https://developers.google.com/chat/images/chat-product-icon.png.

  7. Nhấp vào Lưu.

  8. Để sao chép URL webhook, hãy nhấp vào Tuỳ chọn khác, rồi nhấp vào Sao chép đường liên kết.

Viết tập lệnh webhook

Tập lệnh webhook mẫu sẽ gửi thông báo đến không gian nơi đăng ký webhook bằng cách gửi yêu cầu POST đến URL webhook. Chat API phản hồi bằng một thực thể của Message.

Chọn một ngôn ngữ để tìm hiểu cách tạo tập lệnh webhook:

Python

  1. Trong thư mục đang làm việc, hãy tạo một tệp có tên quickstart.py.

  2. Trong quickstart.py, hãy dán mã sau:

    python/webhook/quickstart.py
    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. Thay thế giá trị cho biến url bằng URL webhook mà bạn đã sao chép khi đăng ký webhook.

Node.js

  1. Trong thư mục đang làm việc, hãy tạo một tệp có tên index.js.

  2. Trong index.js, hãy dán mã sau:

    nút/webhook/index.js
    /**
     * 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. Thay thế giá trị cho biến url bằng URL webhook mà bạn đã sao chép khi đăng ký webhook.

Java

  1. Trong thư mục đang làm việc, hãy tạo một tệp có tên pom.xml.

  2. Trong pom.xml, hãy sao chép và dán nội dung sau:

    java/webhook/pom.xml
    <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. Trong thư mục đang hoạt động, hãy tạo cấu trúc thư mục sau đây src/main/java.

  4. Trong thư mục src/main/java, hãy tạo một tệp có tên App.java.

  5. Trong App.java, hãy dán mã sau:

    java/webhook/src/main/java/com/google/chat/webhook/App.java
    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. Thay thế giá trị cho biến URL bằng URL webhook mà bạn đã sao chép khi đăng ký webhook.

Apps Script

  1. Trên trình duyệt, hãy truy cập vào Apps Script.

  2. Nhấp vào New Project (Dự án mới)

  3. Dán đoạn mã sau:

    apps-script/webhook/webhook.gs
    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. Thay thế giá trị cho biến url bằng URL webhook mà bạn đã sao chép khi đăng ký webhook.

Chạy tập lệnh webhook

Trong CLI, chạy tập lệnh:

Python

  python3 quickstart.py

Node.js

  node index.js

Java

  mvn compile exec:java -Dexec.mainClass=App

Apps Script

  • Nhấp vào Chạy.

Khi bạn chạy mã, webhook sẽ gửi thông báo đến không gian mà bạn đã đăng ký mã.

Bắt đầu hoặc trả lời một chuỗi tin nhắn

  1. Hãy chỉ định spaces.messages.thread.threadKey trong nội dung của yêu cầu thông báo. Tuỳ thuộc vào việc bạn bắt đầu hay trả lời một luồng, hãy sử dụng các giá trị sau cho threadKey:

    • Nếu bắt đầu một luồng, hãy đặt threadKey thành một chuỗi tuỳ ý, nhưng hãy ghi lại giá trị này để đăng câu trả lời cho luồng đó.

    • Nếu trả lời một luồng, hãy chỉ định threadKey được đặt khi luồng bắt đầu. Ví dụ: để đăng trả lời cho luồng mà tin nhắn ban đầu sử dụng MY-THREAD, hãy đặt MY-THREAD.

  2. Xác định hành vi của luồng nếu không tìm thấy threadKey được chỉ định:

    • Trả lời một chuỗi cuộc trò chuyện hoặc bắt đầu một chuỗi cuộc trò chuyện mới. Hãy thêm thông số messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD vào URL webhook. Việc chuyển tham số URL này sẽ khiến Chat tìm một chuỗi hiện có bằng cách sử dụng threadKey đã chỉ định. Nếu tìm thấy một chuỗi, tin nhắn này sẽ được đăng dưới dạng câu trả lời cho chuỗi tin nhắn đó. Nếu không tìm thấy, thì thông báo sẽ bắt đầu một luồng mới tương ứng với threadKey đó.

    • Trả lời một chuỗi tin nhắn hoặc không làm gì cả. Thêm thông số messageReplyOption=REPLY_MESSAGE_OR_FAIL vào URL webhook. Việc chuyển tham số URL này sẽ khiến Chat tìm một chuỗi hiện có bằng cách sử dụng threadKey đã chỉ định. Nếu tìm thấy một chuỗi, tin nhắn này sẽ được đăng dưới dạng câu trả lời cho chuỗi tin nhắn đó. Nếu không tìm thấy tin nhắn thì tin nhắn sẽ không được gửi.

    Để tìm hiểu thêm, hãy xem messageReplyOption.

Mã mẫu sau đây bắt đầu hoặc trả lời một chuỗi tin nhắn:

Python

python/webhook/thread-reply.py
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
/**
 * 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 Script

apps-script/webhook/thread-reply.gs
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);
}