訂閱 Google Chat 活動

本頁面說明 Chat 擴充應用程式可透過 Google Workspace Events API 訂閱的 Chat 事件。決定所需的事件類型後，請建立訂閱項目，開始接收 Chat 的事件。

除了訂閱事件外，您也可以呼叫 Google Chat API 查詢事件。呼叫 Chat API 可讓您定期擷取事件，或補上因服務中斷而可能錯過的訂閱事件。如要瞭解接收及回應 Chat 事件的方式，請參閱 Chat 說明文件中的「處理 Chat 事件」。

支援的 Chat 事件

Google Workspace 訂閱項目可讓您接收 Chat 中下列異動類型的事件：

可監控事件的資源

如要接收事件，請指定要監控的 Chat 資源，也就是訂閱項目的「目標資源」。

Google Workspace Events API 支援下列 Chat 目標資源：

目標資源 格式 限制
空格鍵

//chat.googleapis.com/spaces/SPACE

其中 SPACE 是 Chat API space 資源 資源名稱中的 ID。您可以從聊天室網址或使用 spaces.list() 方法取得 ID。

 授權訂閱項目的 Chat 使用者或 Chat 擴充應用程式，必須是透過 Google Workspace 或 Google 帳戶加入聊天室的成員。支援：
使用者的所有聊天室

//chat.googleapis.com/spaces/-

 訂閱項目只會接收使用者透過 Google Workspace 或 Google 帳戶加入的聊天室事件。僅支援使用者驗證。
User

//cloudidentity.googleapis.com/users/USER

其中 USER 是 Chat API user 資源 資源名稱中的 ID。詳情請參閱「識別及指定 Google Chat 使用者」。

訂閱項目只會接收與授權訂閱的使用者相關的事件。使用者無法代表其他使用者授權訂閱。僅支援使用者驗證。
客戶

//admin.googleapis.com/customers/CUSTOMER

其中 CUSTOMER 是客戶 ID。您也可以使用 my_customer 別名，代表 Chat 應用程式的客戶網域。

訂閱項目會接收客戶網域管理的所有聊天室和使用者事件。僅支援需要管理員核准的應用程式驗證。

建立訂閱項目的事件類型

建立訂閱項目時，請使用 eventTypes[] 欄位指定要接收的事件類型。事件類型會依據 CloudEvents 規格設定格式，例如 google.workspace.APPLICATION.RESOURCE.VERSION.ACTION。

舉例來說，如要接收使用者加入 Chat 聊天室的事件，請將聊天室指定為目標資源，並將事件類型指定為 google.workspace.chat.membership.v1.created。如要接收特定使用者加入任何聊天室的事件，請將該使用者指定為目標資源，並將事件類型指定為 google.workspace.chat.membership.v1.created。如要進一步瞭解事件的運作方式，請參閱「Google Workspace 事件的結構」。

下表列出聊天室訂閱項目和使用者訂閱項目支援的事件類型。如要瞭解事件觸發條件的例外狀況，請參閱「限制」一節。

事件類型 格式 資源資料
訂閱聊天室  
張貼訊息。

google.workspace.chat.message.v1.created

space.message
更新訊息。

google.workspace.chat.message.v1.updated

space.message
刪除訊息。

google.workspace.chat.message.v1.deleted

space.message
建立回應。

google.workspace.chat.reaction.v1.created

space.message.reaction
刪除回應。

google.workspace.chat.reaction.v1.deleted

space.message.reaction
有成員加入聊天室。

google.workspace.chat.membership.v1.created

space.membership
聊天室中的成員已更新。

google.workspace.chat.membership.v1.updated

space.membership
成員從聊天室中移除。

google.workspace.chat.membership.v1.deleted

space.membership
聊天室已更新。

google.workspace.chat.space.v1.updated

space
聊天室已刪除。

google.workspace.chat.space.v1.deleted

space
使用者訂閱方案  
使用者成為聊天室成員。

並非所有新成員都會觸發事件。詳情請參閱「限制」

google.workspace.chat.membership.v1.created

space.membership
更新使用者在聊天室中的成員資格。

google.workspace.chat.membership.v1.updated

space.membership
使用者不再是聊天室的直接成員。

google.workspace.chat.membership.v1.deleted

space.membership
使用者的聊天室已讀狀態已更新。

google.workspace.chat.spaceReadState.v1.updated

spaceReadState
使用者的討論串已讀狀態會更新。

google.workspace.chat.threadReadState.v1.updated

threadReadState
客戶訂閱  
Google Workspace 組織中的任何聊天室、訊息、回應、成員資格或使用者讀取狀態發生事件。

支援聊天室和使用者訂閱項目列出的所有事件類型。

視事件類型而定 (例如 space、space.message、space.membership 或 spaceReadState)。

批次事件類型 (僅限輸出)

除了接收訂閱的事件類型外，Chat 擴充應用程式也可能接收批次事件。批次事件是指在短時間內發生的多個同類型事件。批次事件的酬載包含所有已變更資源的清單。

舉例來說，如果使用者同時將 20 位使用者加入聊天室，Chat 擴充應用程式可能會收到批次事件 (google.workspace.chat.membership.v1.batchCreated)。事件酬載包含使用者將成員加入聊天室時，建立的所有新 Membership 資源清單。

只要訂閱任何事件類型，就會收到批次事件，因此建立訂閱項目時，不必指定批次事件。舉例來說，如果您訂閱新回應 (google.workspace.chat.reaction.v1.created)，Chat 擴充應用程式會自動設定為接收批次回應事件 (google.workspace.chat.reaction.v1.batchCreated)。

下表列出訂閱可能發生的批次事件：

批次事件類型 格式
發布多則訊息。

google.workspace.chat.message.v1.batchCreated
已更新多則訊息。

google.workspace.chat.message.v1.batchUpdated
刪除多則訊息。

google.workspace.chat.message.v1.batchDeleted
建立多個回應。

google.workspace.chat.reaction.v1.batchCreated
已刪除多個回應。

google.workspace.chat.reaction.v1.batchDeleted
多位成員已加入訂閱的聊天室，或訂閱的使用者已加入多個聊天室。

google.workspace.chat.membership.v1.batchCreated
訂閱的聊天室或訂閱的使用者有多個成員資格更新。

google.workspace.chat.membership.v1.batchUpdated
多位成員從訂閱的聊天室中移除，或訂閱的使用者從多個聊天室中移除。

google.workspace.chat.membership.v1.batchDeleted
該空間有多項更新。

google.workspace.chat.space.v1.batchUpdated
訂閱使用者的多個聊天室讀取狀態已更新。

google.workspace.chat.spaceReadState.v1.batchUpdated
系統會為訂閱的使用者更新多個討論串的讀取狀態。

google.workspace.chat.threadReadState.v1.batchUpdated

事件資料

本節說明 Chat 事件的事件資料和酬載範例。

當 Google Workspace 訂閱方案收到 Chat 的事件時，data 欄位會包含事件的酬載。這個酬載包含已變更的 Google Workspace 資源相關資訊。舉例來說，如果您在聊天室中訂閱了成員事件，這些事件的酬載會包含已變更 spaces.membership 資源的相關資訊。

事件酬載中的資源資料

建立訂閱項目時，您可以指定酬載是否要包含資源詳細資料，或只要資源名稱。舉例來說，如果您想接收 Chat 聊天室成員的相關事件，請指定要在事件酬載中接收成員資格資源的哪些欄位。

下表提供訂閱 Chat 聊天室 spaces/AAAABBBBBB 的 JSON 酬載範例。對於訂閱項目收到的每個事件，酬載會顯示在事件的 data 欄位中：

範例 事件類型 JSON 酬載

使用者在聊天室中張貼「Hello world」訊息。

google.workspace.chat.message.v1.created

包含資源資料：

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID",
        "sender":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "2023-09-07T21:37:36.260127Z",
        "text": "Hello world",
        "thread":
        {
            "name": "spaces/SPACE_ID/threads/THREAD_ID"
        },
        "space":
        {
            "name": "spaces/SPACE_ID"
        },
        "argumentText": "Hello world"
    }
}

排除資源資料：

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID"
    }
}
使用者成為聊天室管理員。

google.workspace.chat.membership.v1.updated

包含資源資料：

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID",
        "state": "JOINED",
        "member":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "1970-01-01T00:00:00Z",
        "role": "ROLE_MANAGER"
    }
}

排除資源資料：

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID"
    }
}
使用者將聊天室說明更新為「Cymbal Labs 銷售團隊」。 google.workspace.chat.space.v1.updated

包含資源資料：

{
    "space":
    {
        "name": "spaces/SPACE_ID",
        "displayName": "Cymbal Sales",
        "spaceThreadingState": "THREADED_MESSAGES",
        "spaceType": "SPACE",
        "spaceDetails":
        {
            "description": "Sales team for Cymbal Labs."
        },
        "spaceHistoryState": "HISTORY_ON"
    }
}

排除資源資料：

{
    "space":
    {
        "name": "spaces/SPACE_ID"
    }
}
兩位 Chat 使用者同時加入聊天室。 google.workspace.chat.membership.v1.batchCreated

包含資源資料：

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        }
    ]
}

排除資源資料：

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        }
    ]
}
使用者用 😊 表情符號回應訊息。 google.workspace.chat.reaction.v1.created

包含資源資料：

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        "user":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}

排除資源資料：

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
    }
}
使用者以 😊 和 😸 表情符號回應訊息。 google.workspace.chat.reaction.v1.batchCreated

包含資源資料：

{
    "reactions": [
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😊"
            }
          }
        },
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😸"
            }
          }
        }
    ]
}

排除資源資料：

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
        },
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        }
      }
    ]
}
使用者造訪未讀聊天室，系統會更新聊天室的讀取狀態。 google.workspace.chat.spaceReadState.v1.updated

包含資源資料：

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState",
    "lastReadTime": "2026-04-14T14:03:46.431760Z"
  }
}

排除資源資料：

{
  "spaceReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/spaceReadState"
  }
}
使用者閱讀討論串中的訊息，系統會更新討論串的讀取狀態。 google.workspace.chat.threadReadState.v1.updated

包含資源資料：

{
  "threadReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/threads/THREAD_ID/threadReadState",
    "lastReadTime": "2026-04-14T14:03:46.431760Z"
  }
}

排除資源資料：

{
  "threadReadState": {
    "name": "users/USER_ID/spaces/SPACE_ID/threads/THREAD_ID/threadReadState"
  }
}
使用者在 Chat 中顯示為有空。 google.workspace.chat.availability.v1.updated

包含資源資料：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "ACTIVE"
    }
}

排除資源資料：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
使用者在 Chat 中處於閒置狀態。 google.workspace.chat.availability.v1.updated

包含資源資料：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "IDLE",
    }
}

排除資源資料：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
使用者在 Chat 中將有空與否狀態設為「Away」。 google.workspace.chat.availability.v1.updated

包含資源資料：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "AWAY",
    }
}

排除資源資料：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
使用者在 Chat 中將有空與否狀態設為「Do not disturb」。 google.workspace.chat.availability.v1.updated

包含資源資料：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "DO_NOT_DISTURB",
        "doNotDisturbMetadata": {
          "expirationTime": "2026-03-24T18:36:31.337Z"
        }
    }
}

排除資源資料：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}
使用者在 Chat 設定自訂狀態。 google.workspace.chat.availability.v1.updated

包含資源資料：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
        "state": "ACTIVE",
        "customStatus": {
          "text": "Be right back",
          "emoji": {
            "unicode": "👟"
          },
          "expireTime": "2026-03-24T18:38:05.583655Z"
        }
    }
}

排除資源資料：

{
    "availability":
    {
        "name": "users/USER_ID/availability",
    }
}

限制和傳送行為

一般限制

  • 如要接收成員事件，使用者或 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}