使用 Google Chat 中的活動

本頁面說明 Google Chat 應用程式如何接收並回應 Google Chat 中的事件。

Google Chat 事件代表 Chat 中的活動或變更,例如聊天室中的新訊息。Chat 應用程式可使用事件瞭解發生的情況,並以有意義的方式採取行動或回應使用者。

以下列舉幾個事件用途範例:

  • 監控並回覆聊天室中的新訊息,例如檢查關鍵字或詞組。
  • 使用者加入聊天室時,請傳送歡迎訊息,說明聊天室規範或分享如何有效使用 Chat 應用程式的訣竅。
  • 追蹤及分析 Chat 活動。例如,每月傳送有關新成員或獲得最多回應或回覆的訊息的報表。
  • 透過訊息平台進行通訊。舉例來說,使用者可以在不離開 Chat 的情況下,傳送及接收來自其他訊息平台的訊息。

事件的運作方式

每當 Google 聊天中發生事件時,系統就會建立、更新或刪除 Google 聊天 API 資源。Chat 會透過事件,向 Chat 應用程式提供發生活動類型和受影響的 Chat API 資源相關資訊。

範例:張貼至 Google Chat 聊天室的訊息如何觸發事件。
圖 1. 使用者在 Chat 聊天室中張貼訊息,系統會建立 Message 資源。接著,Chat 會建立事件,其中包含新訊息的資料。

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 應用程式就能開始接收會員事件。

使用 Google Workspace Events API 訂閱事件的 Chat 應用程式。
圖 2. Chat 應用程式會透過使用 Google Workspace Events API 的訂閱項目接收會員事件。

在圖 2 中,Chat 應用程式已訂閱聊天室,因此每當聊天室的成員資格發生變更,應用程式就會收到事件。接著,Chat 應用程式就能即時處理或回應任何活動,例如向加入聊天室的成員發布私人歡迎訊息。

如要瞭解如何使用 Google Workspace Events API 建立訂閱項目,請參閱 Google Workspace Events API 說明文件

查詢最近的會員活動

Chat 應用程式可以呼叫 Chat API,列出與會員活動相關的最近聊天室事件,而非在會員活動發生時收到事件。

使用 Chat API 查詢事件的 Chat 應用程式。
圖 3. 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 群組新增至聊天室」。