使用 Google Chat 中的活動

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

Google Chat 事件代表 Chat 中的活動或變更，例如聊天室中的新訊息。Chat 應用程式可透過事件瞭解事件脈絡，讓使用者以有意義的方式採取行動或做出回應。

以下舉例說明事件的使用方式：

  • 監控及回應聊天室中的新訊息，例如檢查關鍵字或詞組。
  • 在使用者加入聊天室時傳送歡迎訊息、說明聊天室指南，或分享如何有效使用 Chat 應用程式的秘訣。
  • 追蹤及分析 Chat 活動。例如，每月傳送有關新會員，或吸引最多人回應或回覆的訊息報告。
  • 透過各種訊息平台進行通訊。舉例來說，使用者不必離開 Chat，就能與其他訊息平台的使用者收發訊息。

事件的運作方式

只要 Google Chat 中發生的情況，系統就會建立、更新或刪除 Google Chat API 資源。Chat 會使用事件，將已發生的活動類型及受影響的 Chat API 資源提供給 Chat 應用程式。

範例：訊息發布至 Google Chat 聊天室後，會觸發事件。
圖 1.使用者在 Chat 聊天室中張貼訊息，這會建立 Message 資源。Chat 隨後會建立包含新訊息資料的事件。

Chat 會依類型將事件分類。事件類型可協助您篩選及接收所需的資訊類型，並以同樣的方式處理類似活動。

下表列出 Chat 中的活動對相關 Chat API 資源的影響，以及 Chat 應用程式收到的事件類型：

活動 Chat API 資源 事件類型
使用者在 Chat 聊天室中張貼訊息 建立 Message 資源。 新訊息
使用者將成為聊天室管理員。 Membership 資源已更新。 已更新成員
使用者回應訊息。 建立 Reaction 資源。 新回應
使用者離開聊天室。 系統會刪除 Membership 資源。 已刪除會員資格

接收 Google Chat 事件

如要接收事件，Chat 應用程式可以執行下列任一操作：

  • 使用 Google Workspace Event API 訂閱事件，即可在事件發生時接收事件。
  • 呼叫 Chat API 即可查詢近期事件。

下表列出查詢或訂閱事件的差異和原因：

訂閱活動 事件查詢
用途
  • 即時處理或回應事件。
  • 監控使用者的會員活動，探索要監控的新聊天室。
  • 定期或透過觸發條件處理或回應事件。
  • 從訂閱項目擷取錯過的事件 (因為訂閱項目中斷或無效)。
API Google Workspace 事件 API Chat API
事件來源 聊天室和使用者 僅空格
支援的事件
  • 訊息
  • 頻道會員
  • 回應
  • 空格

如需支援的事件類型清單，請參閱 Google Workspace Event API 說明文件中的「 建立訂閱項目的事件類型」。
  • 訊息
  • 頻道會員
  • 回應
  • 空格

如需支援的事件類型清單，請參閱 Chat API 參考說明文件中的 spaceEvents 資源。
事件格式 Google Cloud Pub/Sub 訊息，採用 CloudEvent 規格的格式。詳情請參閱「Google Workspace 事件結構」。 一項 Chat API 資源 ( spaces.spaceEvent)
事件資料 包含或不含資源資料的 Base64 編碼字串。如需酬載範例，請參閱「事件資料」。 包含資源資料的 JSON 酬載。部分事件類型僅包含特定資源欄位。如需酬載範例，請參閱 參考說明文件。

範例：查詢或訂閱聊天室中成員資格的事件

在此範例中，Chat 應用程式想要接收 Chat 聊天室成員異動的相關資訊。在聊天室中，會進行以下成員活動：

  • 使用者加入聊天室，建立 Membership 資源並觸發新的成員事件。
  • 使用者會成為聊天室管理員，這樣會更新使用者的 Membership 資源，並觸發更新的成員事件。
  • 使用者離開聊天室，這樣會刪除使用者的 Membership 資源，並觸發成員刪除的事件。

訂閱會員活動

為了即時接收事件，Chat 應用程式會呼叫 Google Workspace Events API subscriptions.create() 方法，訂閱所有類型的成員資格事件。建立訂閱項目後，Chat 應用程式可以開始接收成員資格事件。

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

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

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

查詢近期成員資格事件

Chat 應用程式可以呼叫 Chat API，列出與成員資格活動相關的近期聊天室事件，而非在成員資格事件發生當下接收事件。

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