Trang này giải thích cách các ứng dụng Google Chat có thể nhận và phản hồi các sự kiện trong Google Chat.
Sự kiện trên Google Chat biểu thị một hoạt động hoặc thay đổi trong Chat, chẳng hạn như tin nhắn mới trong một không gian. Ứng dụng Chat của bạn có thể sử dụng các sự kiện để nắm được những gì đã xảy ra và thực hiện hành động hoặc phản hồi theo cách có ý nghĩa cho người dùng.
Sau đây là một số ví dụ về cách bạn có thể sử dụng sự kiện:
- Theo dõi và trả lời tin nhắn mới trong một không gian, chẳng hạn như kiểm tra các từ khoá hoặc cụm từ.
- Gửi tin nhắn chào mừng cho người dùng khi họ tham gia không gian để giải thích các nguyên tắc của không gian hoặc chia sẻ các mẹo về cách sử dụng hiệu quả ứng dụng Chat.
- Theo dõi và phân tích hoạt động trên Chat. Ví dụ: để gửi báo cáo hằng tháng về thành viên mới hoặc những tin nhắn nhận được nhiều lượt thể hiện cảm xúc hoặc lượt trả lời nhất.
- Giao tiếp trên nhiều nền tảng nhắn tin. Ví dụ: người dùng có thể gửi và nhận tin nhắn từ người dùng trên một nền tảng nhắn tin khác mà không cần rời khỏi Chat.
Cách hoạt động của sự kiện
Bất cứ khi nào có sự kiện xảy ra trong Google Chat, một tài nguyên Google Chat API sẽ được tạo, cập nhật hoặc xoá. Chat sử dụng các sự kiện để gửi thông tin đến ứng dụng Chat của bạn về loại hoạt động đã xảy ra và tài nguyên Chat API bị ảnh hưởng.
Message.
Sau đó, Chat sẽ tạo một sự kiện chứa dữ liệu về tin nhắn mới.Chat phân loại các sự kiện theo loại. Các loại sự kiện giúp bạn lọc và chỉ nhận loại thông tin bạn cần, đồng thời cho phép bạn xử lý các hoạt động tương tự theo cùng một cách.
Bảng sau đây cho biết cách một hoạt động trong Chat ảnh hưởng đến tài nguyên Chat API có liên quan và loại sự kiện mà ứng dụng Chat của bạn nhận được:
| Hoạt động | Tài nguyên Chat API | Loại sự kiện |
|---|---|---|
| Người dùng đăng tin nhắn trong một phòng Chat | Tài nguyên Message được tạo. |
Tin nhắn mới |
| Một người dùng trở thành người quản lý không gian. | Tài nguyên Membership được cập nhật. |
Đã cập nhật gói thành viên |
| Người dùng thể hiện cảm xúc đối với một tin nhắn. | Tài nguyên Reaction được tạo. |
Phản ứng mới |
| Người dùng rời khỏi một không gian. | Một tài nguyên Membership bị xoá. |
Đã xoá gói hội viên |
Nhận sự kiện từ Google Chat
Để nhận sự kiện, ứng dụng Chat của bạn có thể thực hiện một trong những thao tác sau:
- Đăng ký nhận sự kiện bằng Google Workspace Events API để nhận sự kiện khi chúng xảy ra.
- Truy vấn các sự kiện gần đây bằng cách gọi Chat API.
Bảng sau đây giải thích sự khác biệt và lý do truy vấn hoặc đăng ký nhận sự kiện:
| Đăng ký nhận thông báo về sự kiện | Truy vấn sự kiện | |
|---|---|---|
| Trường hợp sử dụng |
|
|
| API | Google Workspace Events API | Chat API |
| Nguồn sự kiện | Không gian, người dùng và tổ chức Google Workspace ( Bản dùng trước cho nhà phát triển) | Chỉ không gian |
| Sự kiện được hỗ trợ |
Để biết danh sách các loại sự kiện được hỗ trợ, hãy xem Các loại sự kiện để tạo gói thuê bao trong tài liệu về Google Workspace Events API. |
Để biết danh sách các loại sự kiện được hỗ trợ, hãy xem tài nguyên spaceEvents trong tài liệu tham khảo về Chat API.
|
| Định dạng sự kiện | Một thông báo Google Cloud Pub/Sub, được định dạng theo quy cách CloudEvent. Để biết thông tin chi tiết, hãy xem bài viết Cấu trúc của các sự kiện trên Google Workspace. |
Tài nguyên Chat API (
spaces.spaceEvent)
|
| Dữ liệu sự kiện | Chuỗi được mã hoá Base64 có hoặc không có dữ liệu tài nguyên. Để biết ví dụ về tải trọng, hãy xem phần Dữ liệu sự kiện. | Tải trọng JSON chứa dữ liệu tài nguyên. Một số loại sự kiện chỉ bao gồm một số trường tài nguyên nhất định. Để biết các tải trọng mẫu, hãy xem tài liệu tham khảo. |
Ví dụ: Truy vấn hoặc đăng ký nhận thông báo về các sự kiện liên quan đến thành viên trong một không gian
Trong ví dụ này, một ứng dụng Chat muốn nhận thông tin về những thay đổi đối với thành viên của một không gian trên Chat. Trong không gian, hoạt động thành viên sau đây sẽ diễn ra:
- Người dùng tham gia phòng, tạo tài nguyên
Membershipvà kích hoạt sự kiện thành viên mới. - Người dùng trở thành người quản lý không gian, việc này sẽ cập nhật tài nguyên
Membershipcho người dùng và kích hoạt sự kiện thành viên được cập nhật. - Người dùng rời khỏi không gian, thao tác này sẽ xoá tài nguyên
Membershipcho người dùng và kích hoạt sự kiện thành viên bị xoá.
Đăng ký nhận thông báo về các sự kiện liên quan đến gói thành viên
Để nhận sự kiện theo thời gian thực, ứng dụng Chat sẽ gọi phương thức Google Workspace Events API subscriptions.create() để đăng ký không gian cho tất cả các loại sự kiện về tư cách thành viên. Sau khi bạn tạo gói thuê bao, ứng dụng Chat có thể bắt đầu nhận các sự kiện về gói thành viên.
Trong hình 2, ứng dụng Chat có một gói thuê bao đang hoạt động cho không gian, vì vậy, ứng dụng sẽ nhận được một sự kiện bất cứ khi nào có thay đổi về tư cách thành viên trong không gian. Sau đó, ứng dụng Chat có thể xử lý hoặc phản hồi theo thời gian thực đối với bất kỳ hoạt động nào, chẳng hạn như đăng một thông điệp chào mừng riêng tư cho thành viên đã tham gia không gian.
Để tìm hiểu về cách tạo lượt đăng ký bằng Google Workspace Events API, hãy xem tài liệu về Google Workspace Events API.
Truy vấn các sự kiện gần đây về tư cách thành viên
Thay vì nhận các sự kiện về thành viên khi chúng xảy ra, ứng dụng Chat có thể gọi Chat API để liệt kê các sự kiện gần đây trong không gian có liên quan đến hoạt động của thành viên.
Trong hình 3, một ứng dụng Chat gọi phương thức Chat API spaces.spaceEvents.list() sau khi tất cả các hoạt động thành viên đã diễn ra và lọc truy vấn cho các sự kiện thành viên mới, đã cập nhật và đã xoá. Chat API trả về danh sách các tài nguyên spaceEvent đại diện cho từng thay đổi về tư cách thành viên.
Sau đó, ứng dụng Chat có thể xử lý hoặc phản hồi dựa trên hoạt động gần đây, chẳng hạn như đăng một tin nhắn hằng tuần kèm theo bản tóm tắt hoạt động của thành viên trong không gian trong 7 ngày qua.
Để truy vấn sự kiện bằng API Chat, hãy xem phần Liệt kê sự kiện trong không gian Google Chat.
Hạn chế và hành vi phân phối
Hạn chế chung
- Để nhận các sự kiện về tư cách thành viên, người dùng hoặc ứng dụng Chat phải là thành viên trực tiếp của không gian. Nếu họ được thêm, cập nhật hoặc xoá gián tiếp khỏi một không gian thông qua một nhóm trên Google Groups, thì dịch vụ đăng ký sẽ không nhận được những sự kiện thành viên đó. Để tìm hiểu cách hoạt động của thành viên trong nhóm trên Google Groups, hãy xem phần Thêm nhóm trên Google Groups vào không gian.
Gói thuê bao của người dùng
-
Đối với việc đăng ký theo dõi người dùng, các sự kiện về thành viên mới trong tin nhắn trực tiếp hoặc cuộc trò chuyện nhóm chưa đặt tên (
google.workspace.chat.membership.v1.created) chỉ kích hoạt sau khi tin nhắn đầu tiên được đăng.
Gói thuê bao của khách hàng ( Bản dùng trước cho nhà phát triển)
Đối với gói thuê bao của khách hàng, các giới hạn sau đây sẽ áp dụng:
- Tổ chức Google Workspace phải có ít nhất một giấy phép SKU Enterprise. Xin lưu ý rằng yêu cầu này không được thực thi nghiêm ngặt trong giai đoạn Chương trình dùng thử cho nhà phát triển, nhưng sẽ được thực thi trong tương lai (sẽ được thông báo riêng).
- Một ứng dụng Chat chỉ có thể tạo một gói thuê bao cho khách hàng đối với một tổ chức Google Workspace nhất định. Một tổ chức Google Workspace có thể có tối đa 5 lượt đăng ký của khách hàng (do các ứng dụng Chat khác nhau tạo).
Đối với lượt đăng ký của khách hàng, việc phân phối sự kiện tuân theo các quy tắc chung sau:
- Sự kiện trong không gian: Chỉ được gửi nếu sự kiện diễn ra trong một không gian do tổ chức Google Workspace của bạn quản lý.
- Sự kiện của người dùng: Chỉ được gửi nếu sự kiện xảy ra cho một người dùng thuộc tổ chức Google Workspace của bạn.
Sự kiện dành cho hội viên là trường hợp ngoại lệ duy nhất đối với các quy tắc này. Gói thuê bao của bạn có thể nhận các sự kiện về thành viên từ cả không gian do tổ chức của bạn quản lý và không gian do các tổ chức bên ngoài quản lý. Tuy nhiên, cách các sự kiện này được gửi sẽ tuỳ thuộc vào tổ chức quản lý không gian:
Không gian do tổ chức Google Workspace của bạn quản lý
Nếu có thay đổi về thành viên trong một không gian do tổ chức Google Workspace quản lý, thì thay đổi đó sẽ được gửi dưới dạng một sự kiện không gian.
Tên tài nguyên của một sự kiện không gian có định dạng như sau:
spaces/{spaceId}/spaceEvents/{spaceEventId}
Không gian do các tổ chức bên ngoài quản lý
Nếu tư cách thành viên của một người dùng do tổ chức Google Workspace của bạn quản lý thay đổi trong một không gian do một tổ chức bên ngoài quản lý (ví dụ: một không gian bên ngoài có tên hoặc một tin nhắn trực tiếp do một người dùng bên ngoài tạo), thì dịch vụ đăng ký của bạn sẽ nhận được sự kiện này dưới dạng một sự kiện người dùng.
Tên tài nguyên của một sự kiện người dùng có định dạng như sau:
users/{userId}/userEvents/{userEventId}
Chủ đề có liên quan
- Tổng quan về Google Workspace Events API
- Tạo gói thuê bao
- Xem thông tin chi tiết về một sự kiện trong không gian Google Chat
- Liệt kê các sự kiện trong một không gian trên Google Chat