提供意見
訂閱 Google Chat 活動
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
本頁說明 Google Chat 應用程式可使用 Google Workspace Events API 訂閱的 Google Chat 事件。決定需要哪些類型的事件後,請建立訂閱項目 ,開始接收 Google Chat 的事件。
除了訂閱事件,您也可以呼叫 Chat API 查詢事件。呼叫 Chat API 可定期擷取事件,或補捉因服務中斷而可能錯過的訂閱事件。如要瞭解接收及回覆 Chat 事件的方式,請參閱 Chat 說明文件中的「處理 Google Chat 事件 」。
支援的 Chat 事件
透過 Google Workspace 訂閱方案,您可以接收有關下列 Chat 變更類型的事件:
聊天室中新增、更新或刪除的訊息 。
訊息新增或移除回應 。
聊天室中新增、更新或移除成員 。
你訂閱的空間 有異動,例如空間名稱或說明更新。
可監控事件的資源
如要接收事件,請指定要監控的 Chat 資源,這類資源稱為訂閱的目標資源 。
Google Workspace Events API 支援下列 Chat 目標資源:
目標資源
格式
限制
空格
//chat.googleapis.com/spaces/SPACE
其中 SPACE 是 Chat API space
資源的
資源名稱 中的 ID。您可以從空間的網址取得 ID,或使用
spaces.list()
方法。
授權訂閱的 Chat 使用者或 Chat 應用程式必須透過 Google Workspace 或 Google 帳戶成為聊天室成員。支援:
使用者的所有空間
//chat.googleapis.com/spaces/-
訂閱項目只會接收使用者透過 Google Workspace 或 Google 帳戶加入的聊天室活動。僅支援使用者驗證 。
使用者
//cloudidentity.googleapis.com/users/USER
其中 USER 是 Chat API user
資源的
資源名稱 中的 ID。詳情請參閱「識別及指定 Google 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
批次事件類型 (僅限輸出)
除了訂閱的事件類型外,您的 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
事件資料
本節說明 Chat 事件的事件資料和有效負載範例。
當 Google Workspace 訂閱方案收到 Chat 的事件時,data
欄位會包含該事件的酬載。這個酬載包含變更的 Google Workspace 資源相關資訊。舉例來說,如果您已訂閱空間中的成員活動,這些活動的酬載會包含變更的 spaces.membership
資源相關資訊。
事件酬載中的資源資料
建立訂閱項目時,您可以指定要在酬載中加入資源詳細資料,還是只加入資源名稱。舉例來說,如要接收有關 Google 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.membership.v1.created
) 中新成員的事件。
如要接收成員事件,使用者或 Chat 應用程式必須是聊天室的直接成員。如果使用者是透過 Google 群組間接新增、更新或移除聊天室,訂閱項目不會收到這些成員事件。如要瞭解 Google 群組成員資格的運作方式,請參閱「將 Google 群組新增至聊天室 」。
提供意見
除非另有註明,否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權 ,程式碼範例則為阿帕契 2.0 授權 。詳情請參閱《Google Developers 網站政策 》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間:2025-09-20 (世界標準時間)。
想進一步說明嗎?
[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["缺少我需要的資訊","missingTheInformationINeed","thumb-down"],["過於複雜/步驟過多","tooComplicatedTooManySteps","thumb-down"],["過時","outOfDate","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["示例/程式碼問題","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間:2025-09-20 (世界標準時間)。"],[[["\u003cp\u003eGoogle Chat apps can subscribe to events like new messages, reactions, membership changes, and space updates using the Google Workspace Events API.\u003c/p\u003e\n"],["\u003cp\u003eSubscriptions can target specific spaces, all spaces for a user, or a specific user, enabling customized event delivery.\u003c/p\u003e\n"],["\u003cp\u003eEvent types are specified when creating subscriptions, with options for receiving detailed resource data or just resource names.\u003c/p\u003e\n"],["\u003cp\u003eBatch events are automatically included, grouping multiple similar events for efficiency.\u003c/p\u003e\n"],["\u003cp\u003eCertain limitations apply, such as requiring direct space membership for membership events and initial message posting for direct message/unnamed group chat membership events.\u003c/p\u003e\n"]]],["Google Chat apps can use the Google Workspace Events API to subscribe to events or query them via the Chat API. Subscribable events include new, updated, or deleted messages, reactions, and members in a space, as well as changes to the space itself. Target resources for subscriptions can be a specific space, all spaces for a user, or a user. Subscriptions can include resource data, and they automatically support batch events. Event types are available for space subscriptions and user subscriptions with some specific limitations.\n"],null,[]]