本頁面說明 Google Chat 應用程式如何接收並回應 Google Chat 中的事件。
Google Chat 事件代表 Chat 中的活動或變更,例如聊天室中的新訊息。Chat 應用程式可使用事件瞭解發生的情況,並以有意義的方式採取行動或回應使用者。
以下列舉幾個事件用途範例:
- 監控並回覆聊天室中的新訊息,例如檢查關鍵字或詞組。
- 使用者加入聊天室時,請傳送歡迎訊息,說明聊天室規範或分享如何有效使用 Chat 應用程式的訣竅。
- 追蹤及分析 Chat 活動。例如,每月傳送有關新成員或獲得最多回應或回覆的訊息的報表。
- 透過訊息平台進行通訊。舉例來說,使用者可以在不離開 Chat 的情況下,傳送及接收來自其他訊息平台的訊息。
事件的運作方式
每當 Google 聊天中發生事件時,系統就會建立、更新或刪除 Google 聊天 API 資源。Chat 會透過事件,向 Chat 應用程式提供發生活動類型和受影響的 Chat API 資源相關資訊。
Chat 會依類型分類事件。事件類型可協助您篩選並接收所需的資訊類型,並以相同方式處理類似的活動。
下表說明 Chat 中的活動如何影響相關的 Chat API 資源,以及 Chat 應用程式收到的事件類型:
活動 | Chat API 資源 | 事件類型 |
---|---|---|
使用者在 Chat 聊天室中張貼訊息 | 建立 Message 資源。 |
新訊息 |
使用者成為聊天室管理員。 | 已更新 Membership 資源。 |
已更新會員資格 |
使用者回應訊息。 | 建立 Reaction 資源。 |
新回應 |
使用者離開聊天室。 | 已刪除 Membership 資源。 |
已刪除的會員 |
接收 Google Chat 事件
如要接收事件,Chat 應用程式可以執行下列任一操作:
- 使用 Google Workspace Events API 訂閱事件,即可在事件發生時收到通知。
- 呼叫 Chat API 以查詢近期事件。
下表說明查詢或訂閱事件的差異和原因:
訂閱事件 | 查詢事件 | |
---|---|---|
用途 |
|
|
API | Google Workspace Events API | Chat API |
事件來源 | 聊天室和使用者 | 僅限聊天室 |
支援的事件 |
如需支援的事件類型清單,請參閱 Google Workspace Events API 說明文件中的「 建立訂閱項目的事件類型」。 |
如需支援的事件類型清單,請參閱 Chat API 參考資料說明文件中的 spaceEvents 資源。
|
事件格式 | 根據 CloudEvent 規格設定格式的 Google Cloud Pub/Sub 訊息。詳情請參閱「Google Workspace 事件的結構」。 |
Chat API 資源 (
spaces.spaceEvent ) |
事件資料 | 含有或不含資源資料的 Base64 編碼字串。如需瞭解酬載的相關資訊,請參閱「事件資料」。 | 包含資源資料的 JSON 酬載。部分事件類型只包含特定資源欄位。如需酬載範例,請參閱 參考說明文件。 |
範例:查詢或訂閱聊天室中會員相關事件
在這個範例中,Chat 應用程式想要接收 Chat 聊天室成員變更的相關資訊。在聊天室中,會發生以下會員活動:
- 使用者加入聊天室,系統會建立
Membership
資源並觸發新成員事件。 - 使用者成為聊天室管理員,系統會為使用者更新
Membership
資源,並觸發更新的會員事件。 - 使用者離開聊天室,系統會刪除使用者的
Membership
資源,並觸發成員刪除事件。
訂閱會員事件
為了即時接收事件,Chat 應用程式會呼叫 Google Workspace Events API subscriptions.create()
方法,訂閱聊天室的所有會員事件。建立訂閱項目後,Chat 應用程式就能開始接收會員事件。
在圖 2 中,Chat 應用程式已訂閱聊天室,因此每當聊天室的成員資格發生變更,應用程式就會收到事件。接著,Chat 應用程式就能即時處理或回應任何活動,例如向加入聊天室的成員發布私人歡迎訊息。
如要瞭解如何使用 Google Workspace Events API 建立訂閱項目,請參閱 Google Workspace Events API 說明文件。
查詢最近的會員活動
Chat 應用程式可以呼叫 Chat API,列出與會員活動相關的最近聊天室事件,而非在會員活動發生時收到事件。
在圖 3 中,Chat 應用程式會在所有會員活動發生後呼叫 Chat API spaces.spaceEvents.list()
方法,並篩選新會員事件、更新會員事件和已刪除會員事件的查詢。Chat API 會傳回 spaceEvent
資源清單,代表每個會員變更。接著,Chat 應用程式就能根據近期活動進行處理或回應,例如每週發布訊息,並摘要列出過去 7 天內聊天室的會員活動。
如要使用 Chat API 查詢事件,請參閱「列出 Google Chat 聊天室的事件」。
限制
-
針對使用者訂閱,直接訊息或未命名的群組通訊 (
google.workspace.chat.membership.v1.created
) 中新成員的事件,只會在發布第一則訊息後觸發。 - 如要接收會員事件,使用者必須是聊天室的直接成員。如果使用者是透過 Google 群組間接加入聊天室、更新或移除,訂閱項目就不會收到這些會員事件。如要瞭解 Google 群組會員資格運作方式,請參閱「將 Google 群組新增至聊天室」。
相關主題
- Google Workspace Events API 總覽
- 建立訂閱項目
- 取得 Google Chat 聊天室事件的詳細資料
- 列出 Google Chat 聊天室中的事件
- 如需使用事件的範例,請參閱教學課程「透過 Gemini AI Chat 擴充應用程式,依據 Chat 對話回答問題」,或是程式碼研究室「運用 Gemini 打造 Google Chat 擴充應用程式」中的「問題管理 Chat 應用程式」的包容性說明功能。