Trang này mô tả cách thiết lập webhook để gửi thông báo không đồng bộ vào một không gian Chat bằng các trình 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 điện thoại trên Chat khi máy chủ gặp sự cố. Để gửi tin nhắn đồng bộ bằng ứ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 đã kết nối vì hoạt động giao tiếp là một chiều. Webhook không phải là tính năng trò chuyện. Các bot không thể phản hồi hoặc nhận tin nhắn từ người dùng hoặc sự kiện tương tác với ứng dụng trò chuyện. Để phản hồ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à một ứng dụng Chat (webhook kết nối các ứng dụng bằng cách sử dụng các yêu cầu HTTP tiêu chuẩn), nhưng trang này gọi webhook là ứng dụng Chat để đơn giản hoá. Mỗi webhook chỉ hoạt động trong phòng Chat mà webhook đó được đăng ký. Webhook đến 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 ứng dụng Chat. Bạn không thể xuất bản webhook lên Google Workspace Marketplace.
Sơ đồ sau đây cho thấy cấu trúc của một webhook được kết nối với Chat:
Trong sơ đồ trước, ứng dụng Chat có quy trình thông tin sau:
- Logic ứng dụng Chat nhận thông tin từ các dịch vụ bên thứ ba bên ngoài, chẳng hạn như hệ thống quản lý dự án hoặc công cụ tạo phiếu yêu cầu hỗ trợ.
- Logic ứng dụng Chat được lưu trữ trong một hệ thống trên đám mây hoặc tại chỗ có thể gửi tin nhắn bằng cách sử dụng URL webhook đến một không gian Chat cụ thể.
- Người dùng có thể nhận tin nhắn từ ứng dụng Chat trong không gian 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
- Tài khoản Google Workspace dành cho doanh nghiệp hoặc doanh nghiệp lớn có quyền truy cập vào Google 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.6 trở lên
- Công cụ quản lý gói pip
Thư viện
httplib2
. Để cài đặt thư viện, hãy chạy lệnh sau trong giao diện dòng lệnh:pip install httplib2
Một phòng Google Chat. Để tạo không gian bằng API Google Chat, hãy xem phần Tạo không gian. Để tạo một kênh trong Chat, hãy truy cập vào tài liệu trong Trung tâm trợ giúp.
Node.js
- Tài khoản Google Workspace dành cho doanh nghiệp hoặc doanh nghiệp lớn có quyền truy cập vào Google 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.
- Node.js 14 trở lên
- Công cụ quản lý gói npm
- Một phòng Google Chat. Để tạo không gian bằng API Google Chat, hãy xem phần Tạo không gian. Để tạo một kênh trong Chat, hãy truy cập vào tài liệu trong Trung tâm trợ giúp.
Java
- Tài khoản Google Workspace dành cho doanh nghiệp hoặc doanh nghiệp lớn có quyền truy cập vào Google 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.
- Java 11 trở lên
- Công cụ quản lý gói Maven
- Một phòng Google Chat. Để tạo không gian bằng API Google Chat, hãy xem phần Tạo không gian. Để tạo một kênh trong Chat, hãy truy cập vào tài liệu trong Trung tâm trợ giúp.
Apps Script
- Tài khoản Google Workspace dành cho doanh nghiệp hoặc doanh nghiệp lớn có quyền truy cập vào Google 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.
- Tạo một dự án Apps Script độc lập và bật Dịch vụ trò chuyện nâng cao.
- Một phòng Google Chat. Để tạo không gian bằng API Google Chat, hãy xem phần Tạo không gian. Để tạo một kênh trong Chat, hãy truy cập vào tài liệu trong Trung tâm trợ giúp.
Tạo webhook
Để tạo webhook, hãy đăng ký webhook đó trong không gian Chat mà bạn muốn nhận tin nhắn, sau đó viết tập lệnh gửi tin nhắn.
Đăng ký webhook đến
- Trong trình duyệt, hãy mở Chat. Bạn không thể định cấu hình webhook từ ứng dụng Chat dành cho thiết bị di động.
- Chuyển đến không gian mà bạn muốn thêm webhook.
- Bên cạnh tiêu đề của không gian, hãy nhấp vào biểu tượng mũi tên mở rộng , rồi nhấp vào Ứng dụng và công cụ tích hợp.
Nhấp vào
Thêm webhook.Trong trường Name (Tên), hãy nhập
Quickstart Webhook
.Trong trường Avatar URL (URL hình đại diện), hãy nhập
https://developers.google.com/chat/images/chat-product-icon.png
.Nhấp vào Lưu.
Để sao chép URL webhook, hãy nhấp vào biểu tượng
Tuỳ chọn khác, sau đó nhấp vào biểu tượng Sao chép đường liên kết.
Viết tập lệnh webhook
Tập lệnh webhook mẫu gửi thông báo đến không gian mà webhook được đăng ký 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
Trong thư mục đang hoạt động, hãy tạo một tệp có tên
quickstart.py
.Trong
quickstart.py
, hãy dán mã sau:Thay thế giá trị của biến
url
bằng URL webhook mà bạn đã sao chép khi đăng ký webhook.
Node.js
Trong thư mục đang hoạt động, hãy tạo một tệp có tên
index.js
.Trong
index.js
, hãy dán mã sau:Thay thế giá trị của biến
url
bằng URL webhook mà bạn đã sao chép khi đăng ký webhook.
Java
Trong thư mục đang hoạt động, hãy tạo một tệp có tên
pom.xml
.Trong
pom.xml
, hãy sao chép và dán nội dung sau:Trong thư mục đang hoạt động, hãy tạo cấu trúc thư mục
src/main/java
sau.Trong thư mục
src/main/java
, hãy tạo một tệp có tênApp.java
.Trong
App.java
, hãy dán mã sau:Thay thế giá trị cho biến
URL
bằng URL webhook mà bạn đã sao chép khi đăng ký webhook.
Apps Script
Trên trình duyệt, hãy truy cập vào Apps Script.
Nhấp vào New Project (Dự án mới)
Dán mã sau:
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, hãy 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 một thông báo đến không gian mà bạn đã đăng ký webhook.
Bắt đầu hoặc trả lời chuỗi tin nhắn
Chỉ định
spaces.messages.thread.threadKey
trong phần nội dung yêu cầu gửi tin nhắn. Tuỳ thuộc vào việc bạn đang bắt đầu hay trả lời một chuỗi tin nhắn, hãy sử dụng các giá trị sau chothreadKey
:Nếu bắt đầu một chuỗi tin nhắn, hãy đặt
threadKey
thành một chuỗi tuỳ ý, nhưng ghi lại giá trị này để đăng một tin nhắn trả lời cho chuỗi tin nhắn đó.Nếu trả lời một chuỗi tin nhắn, hãy chỉ định
threadKey
đã được đặt khi bắt đầu chuỗi tin nhắn. Ví dụ: để đăng một câu trả lời cho chuỗi tin nhắn mà tin nhắn ban đầu sử dụngMY-THREAD
, hãy đặtMY-THREAD
.
Xác định hành vi của luồng nếu không tìm thấy
threadKey
đã chỉ định:Trả lời một chuỗi tin nhắn hoặc bắt đầu một chuỗi tin nhắn mới. Thêm tham số
messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD
vào URL webhook. Việc truyền tham số URL này sẽ khiến Chat tìm một chuỗi tin nhắn hiện có bằngthreadKey
đã chỉ định. Nếu tìm thấy một chuỗi tin nhắn, thì thư sẽ được đăng dưới dạng thư trả lời 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ớithreadKey
đó.Trả lời chuỗi tin nhắn hoặc không làm gì cả. Thêm tham số
messageReplyOption=REPLY_MESSAGE_OR_FAIL
vào URL webhook. Việc truyền tham số URL này sẽ khiến Chat tìm một chuỗi tin nhắn hiện có bằngthreadKey
đã chỉ định. Nếu tìm thấy một chuỗi tin nhắn, thì thư sẽ được đăng dưới dạng thư trả lời chuỗi tin nhắn đó. Nếu không tìm thấy, thì thông báo 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
Node.js
Apps Script
Xử lý lỗi
Yêu cầu webhook có thể không thành công vì nhiều lý do, bao gồm:
- Yêu cầu không hợp lệ.
- Webhook hoặc không gian lưu trữ webhook đó sẽ bị xoá.
- Các vấn đề gián đoạn như kết nối mạng hoặc hạn mức hạn mức.
Khi tạo webhook, bạn nên xử lý các lỗi một cách thích hợp bằng cách:
- Đang ghi lại lỗi.
- Đối với lỗi dựa trên thời gian, hạn mức hoặc kết nối mạng, hãy thử lại yêu cầu bằng thuật toán thời gian đợi luỹ thừa.
- Không làm gì cả, điều này phù hợp nếu việc gửi thông báo webhook không quan trọng.
API Google Chat trả về lỗi dưới dạng google.rpc.Status
, bao gồm lỗi HTTP code
cho biết loại lỗi đã gặp: lỗi máy khách (dòng 400) hoặc lỗi máy chủ (dòng 500). Để xem lại tất cả các mối liên kết HTTP, hãy xem google.rpc.Code
.
{
"code": 503,
"message": "The service is currently unavailable.",
"status": "UNAVAILABLE"
}
Để tìm hiểu cách diễn giải mã trạng thái HTTP và xử lý lỗi, hãy xem phần Lỗi.
Các điểm hạn chế và điều cần cân nhắc
- Khi tạo tin nhắn bằng webhook trong API Google Chat, phản hồi sẽ không chứa toàn bộ tin nhắn.
Phản hồi chỉ điền vào các trường
name
vàthread.name
. - Webhook tuân theo giới hạn
spaces.messages.create
mỗi truy vấn trên không gian là 60 truy vấn mỗi 60 giây, được chia sẻ giữa tất cả ứng dụng Chat trong không gian. Để biết thêm thông tin về hạn mức API Chat, hãy xem phần Hạn mức sử dụng.