使用 Google Chat 中的活動

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

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

以下列舉幾個事件用途：

  • 監控及回覆聊天室中的新訊息，例如檢查關鍵字或詞組。
  • 在使用者加入聊天室時傳送歡迎訊息，說明聊天室規範，或分享如何有效使用 Chat 擴充應用程式。
  • 追蹤及分析 Chat 活動。例如，傳送新成員或最多人回應/回覆的訊息月報。
  • 跨訊息平台通訊。舉例來說，使用者不必離開 Chat，就能與其他訊息平台的使用者收發訊息。

事件的運作方式

每當 Google Chat 發生事件時，系統就會建立、更新或刪除 Google Chat 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 機構 ( 開發人員預覽版) 僅限聊天室
支援的事件
  • 訊息
  • 頻道會員
  • 回應
  • 空格鍵

如需支援的事件類型清單，請參閱 Google Workspace Events 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 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 聊天室中的事件」。

限制和傳送行為

一般限制

  • 如要接收成員事件，使用者或 Chat 擴充應用程式必須是聊天室的直接成員。如果使用者是透過 Google 群組間接新增、更新或移除，訂閱項目就不會收到這些成員資格事件。如要瞭解 Google 群組成員資格的運作方式，請參閱「將 Google 群組新增至聊天室」。

使用者訂閱方案

  • 如果是訂閱使用者，只有在發布第一則訊息後，才會觸發即時訊息或未命名群組通訊 (google.workspace.chat.membership.v1.created) 中新成員的事件。

客戶訂閱

客戶訂閱方案有以下限制：

  • Google Workspace 組織必須至少有一份 Enterprise SKU 授權。
  • Chat 擴充應用程式只能為特定 Google Workspace 組織建立一個客戶訂閱項目。一個 Google Workspace 機構最多可有五個客戶訂閱項目 (由不同 Chat 擴充應用程式建立)。

如果是客戶訂閱項目，事件傳送作業會遵循下列一般規則：

  • 聊天室事件：只有在事件發生於 Google Workspace 組織管理的聊天室時，才會傳送。
  • 使用者事件：只有在事件發生於 Google Workspace 組織的使用者時，才會傳送。

這些規則唯一的例外狀況是會員活動。訂閱項目可以接收貴機構和外部機構管理的聊天室成員事件，但傳送方式取決於管理聊天室的機構：

由 Google Workspace 組織管理的聊天室

如果 Google Workspace 機構管理的聊天室發生會員異動，系統會以聊天室事件的形式傳送。

聊天室事件的資源名稱格式如下：

spaces/{spaceId}/spaceEvents/{spaceEventId}

由外部機構管理的聊天室

如果由 Google Workspace 組織管理的使用者，在外部組織管理的聊天室 (例如外部具名聊天室或外部使用者建立的即時訊息) 中成員資格發生變更，訂閱項目會將這類事件視為使用者事件。

使用者事件的資源名稱格式如下：

users/{userId}/userEvents/{userEventId}