本頁面說明 Google Chat 應用程式可從 Google Chat 接收的互動事件類型。
如要設定 Chat 應用程式來接收互動事件,請參閱接收及回應與 Chat 應用程式的互動。
互動事件格式
使用者可以透過許多方式與 Chat 專用應用程式互動。Google Chat 會針對每種互動類型傳送不同的互動事件:
- 訊息:使用者傳送 Chat 應用程式訊息,或在聊天室中叫用 Chat 應用程式。
- 新增至聊天室:使用者將您的 Chat 應用程式新增至聊天室。
- 從聊天室中移除:使用者已從聊天室中移除您的 Chat 應用程式。
- 已點選的資訊卡:使用者按一下 Chat 應用程式傳送的互動式資訊卡或對話方塊。
每次使用者與 Chat 應用程式互動時,Google Chat 都會傳送互動事件與「要求主體」,這是代表互動的 JSON 酬載。此事件酬載包含所有類型互動事件都通用的元素,以及該事件類型專用的元素。
如要進一步瞭解互動事件中的欄位,請參閱 Google Chat API 的 Event
參考說明文件。
常用欄位
下列欄位一律會在互動事件的酬載中提供:
欄位 | 說明 |
---|---|
type |
Chat 應用程式接收的事件類型,例如 MESSAGE 或 ADDED_TO_SPACE 。 |
eventTime |
時間戳記會指出事件的分派時間。 |
common |
代表使用者用戶端的相關資訊,例如語言代碼或平台。 |
按互動事件類型劃分的欄位
視事件類型而定,酬載可能會包含下列額外欄位:
欄位 | 說明 | 事件類型 |
---|---|---|
message |
與事件相關的訊息。 | MESSAGE ,ADDED_TO_SPACE ,CARD_CLICKED 。 |
space |
與活動相關的聊天室。 | MESSAGE ,ADDED_TO_SPACE ,REMOVED_FROM_SPACE ,CARD_CLICKED 。 |
user |
與事件相關的使用者。使用者一律是個人使用者 (而非 Chat 應用程式)。 | MESSAGE ,ADDED_TO_SPACE ,REMOVED_FROM_SPACE ,CARD_CLICKED 。 |
action |
使用者點選互動式資訊卡或對話方塊時觸發的函式。 | CARD_CLICKED 。 |
事件酬載範例
本節說明會觸發互動事件的因素,並提供下列每種事件類型的 JSON 酬載範例:
訊息
這項互動事件代表使用者傳送訊息給 Chat 應用程式的時間點,例如:
- 與 Chat 應用程式一起在即時訊息 (DM) 聊天室中的任何訊息。
- 多人聊天室中的訊息,使用者使用 @號提及 Chat 應用程式,或使用其中一個斜線指令。
- 如果您已為 Chat 應用程式設定連結預覽,使用者就會發布訊息,其中包含符合設定網址模式的連結。
以下 JSON 範例是 MESSAGE
互動事件,其中使用者在有多位使用者的聊天室中使用 @ 提及 Chat 應用程式:
{
"type": "MESSAGE",
"eventTime": {
"seconds": 1691187414,
"nanos": 93489000
},
"space": {
"name": "spaces/AAAAAAAAAAA",
"displayName": "Customer Support Superstars",
"spaceType": "SPACE"
},
"message": {
"name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
"sender": {
"name": "users/12345678901234567890",
"displayName": "Izumi",
"avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
"email": "izumi@example.com"
},
"createTime": {
"seconds": 1691187386,
"nanos": 954319000
},
"text": "@TestBot Create ticket.",
"argumentText": " Create ticket.",
"thread": {
"name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB",
"threadKey": "custom-thread-ID"
},
"annotations": [
{
"length": 8,
"startIndex": 0,
"userMention": {
"type": "MENTION",
"user": {
"avatarUrl": "https://.../avatar.png",
"displayName": "TestBot",
"name": "users/1234567890987654321",
"type": "BOT"
}
},
"type": "USER_MENTION"
}
],
"attachment": [
{
"name": "spaces/5o6pDgAAAAE/messages/Ohu1LlUVcS8.Ohu1LlUVcS8/attachments/AATUf-Iz7d8kySEdRRZd-dznqBk3",
"content_name": "solar.png",
"content_type": "image/png",
"drive_data_ref": {
"drive_file_id": "H1HqaqRuH2Pfd_TOa1fF2_ltwDlV_yKRrr"
},
"source": "DRIVE_FILE"
}
]
},
"user": {
"name": "users/12345678901234567890",
"displayName": "Izumi",
"avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
"email": "izumi@example.com"
}
}
已新增至聊天室
這個互動事件表示您的 Chat 應用程式已新增至聊天室。應用程式通常會透過在聊天室中的新討論串張貼某種歡迎訊息,以回應這個互動事件。
以下 JSON 範例顯示使用者將 Chat 應用程式新增至聊天室時,ADDED_TO_SPACE
互動事件的要求主體:
{
"type": "ADDED_TO_SPACE",
"eventTime": {
"seconds": 1691187414,
"nanos": 93489000
},
"space": {
"name": "spaces/AAAAAAAAAAA",
"displayName": "Customer Support Superstars",
"spaceType": "SPACE",
"adminInstalled": "false"
},
"user": {
"name": "users/12345678901234567890",
"displayName": "Izumi",
"avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
"email": "izumi@example.com"
}
}
由 Google Workspace 管理員安裝
ADDED_TO_SPACE
互動事件也可以表示 Google Workspace 管理員已為機構中的使用者安裝您的 Chat 應用程式。
管理員只能針對 Chat 應用程式與使用者之間的即時訊息安裝 Chat 應用程式。已安裝的應用程式會顯示在使用者的即時訊息面板中。管理員安裝 Chat 專用應用程式時,使用者無法解除安裝。如要瞭解管理員安裝的 Chat 應用程式,請參閱 Google Workspace 管理員說明文件的「在網域內安裝 Marketplace 中的應用程式」。
以下 JSON 範例顯示 Google Workspace 管理員為使用者安裝 Chat 應用程式時,ADDED_TO_SPACE
互動事件的要求主體。由於管理員已安裝 Chat 應用程式,因此 adminInstalled
會設為 true
:
{
"type": "ADDED_TO_SPACE",
"eventTime": {
"seconds": 1691187414,
"nanos": 93489000
},
"space": {
"name": "spaces/AAAAAAAAAAA",
"displayName": "Customer Support Superstars",
"spaceType": "DIRECT_MESSAGE",
"adminInstalled": "true"
},
"user": {
"name": "users/12345678901234567890",
"displayName": "Izumi",
"avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
"email": "izumi@example.com"
}
}
已從聊天室中移除
這個互動事件表示 Chat 應用程式已從聊天室中移除。Chat 應用程式已經移除,因此不會回覆此活動的訊息。
以下 JSON 範例顯示使用者從聊天室中移除 Chat 應用程式時,REMOVED_FROM_SPACE
互動事件的要求主體:
{
"type": "REMOVED_FROM_SPACE",
"eventTime": {
"seconds": 1691187414,
"nanos": 93489000
},
"space": {
"name": "spaces/AAAAAAAAAAA",
"spaceType": "SPACE",
"adminInstalled": "false"
},
"user": {
"name": "users/12345678901234567890",
"displayName": "Izumi",
"avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
"email": "izumi@example.com"
}
}
Google Workspace 管理員已解除安裝
REMOVED_FROM_SPACE
互動事件也可表示 Google Workspace 管理員已為機構中的使用者解除安裝您的 Chat 應用程式。解除安裝 Chat 應用程式後,使用者的即時訊息面板中就不會再顯示該應用程式。
如果使用者在管理員之前就已安裝 Chat 應用程式,系統會為該使用者保留安裝 Chat 應用程式。在此情況下,由於 Chat 應用程式仍未安裝,因此 Chat 應用程式不會收到 REMOVED_FROM_SPACE
互動事件。
以下 JSON 範例顯示 Google Workspace 管理員為使用者解除安裝 Chat 應用程式時,REMOVED_FROM_SPACE
互動事件的要求主體。由於管理員已解除安裝 Chat 應用程式,因此 adminInstalled
會設為 true
:
{
"type": "REMOVED_FROM_SPACE",
"eventTime": {
"seconds": 1691187414,
"nanos": 93489000
},
"space": {
"name": "spaces/AAAAAAAAAAA",
"spaceType": "DIRECT_MESSAGE",
"adminInstalled": "true"
},
"user": {
"name": "users/12345678901234567890",
"displayName": "Izumi",
"avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
"email": "izumi@example.com"
}
}
已點選資訊卡
這個互動事件表示使用者點選資訊卡訊息或對話方塊中的按鈕。
如要接收互動事件,按鈕必須觸發與 Chat 應用程式的另一項互動。舉例來說,如果使用者點選開啟網站連結的按鈕前往網站,卻收到互動事件,則 Chat 應用程式不會收到 CARD_CLICKED
互動事件,如以下範例所示:
- 使用者點選資訊卡中的
Send feedback
按鈕,即可開啟用於輸入資訊的對話方塊。 - 使用者在資訊卡或對話方塊中輸入資訊後,按一下
Submit
按鈕。
以下 JSON 範例顯示當使用者按一下資訊卡訊息中的按鈕,將收到的支援單指派給自己時,CARD_CLICKED
互動事件的要求主體:
{
"type": "CARD_CLICKED",
"eventTime": {
"seconds": 1691187414,
"nanos": 93489000
},
"common": {
"userLocale": "en",
"hostApp": "CHAT",
"invokedFunction": "doAssignTicket",
"timeZone": {
"offset": -25200000,
"id": "America/Los_Angeles"
}
},
"action": {
"actionMethodName": "doAssignTicket"
},
"message": {
"cards": [
{
"header": {
"title": "Incoming support ticket."
},
"sections": [
{
"widgets": [
{
"textParagraph": {
"text": "Incoming support ticket #12345 is unassigned and needs your attention."
}
},
{
"buttons": [
{
"textButton": {
"onClick": {
"action": {
"actionMethodName": "doAssignTicket"
}
},
"text": "Assign to me"
}
}
]
}
]
}
]
}
],
"sender": {
"avatarUrl": "https://www.example.com/images/chat-app-icon.png",
"displayName": "Support Chat app",
"name": "users/98765432109876543210",
"type": "BOT"
},
"createTime": {
"seconds": 1691187386,
"nanos": 954319000
},
"retentionSettings": {
"state": "PERMANENT"
},
"name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
"thread": {
"retentionSettings": {
"state": "PERMANENT"
},
"name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB"
},
"messageHistoryState": "HISTORY_ON",
"space": {
"spaceThreadingState": "GROUPED_MESSAGES",
"spaceType": "SPACE",
"displayName": "Customer Support Superstars",
"name": "spaces/AAAAAAAAAAA",
"spaceHistoryState": "HISTORY_ON",
"type": "ROOM",
"threaded": true
}
},
"user": {
"avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
"displayName": "Izumi",
"name": "users/12345678901234567890",
"type": "HUMAN",
"email": "izumi@example.com",
"domainId": "ABCDEFG"
},
"space": {
"spaceThreadingState": "GROUPED_MESSAGES",
"spaceType": "SPACE",
"displayName": "Customer Support Superstars",
"name": "spaces/AAAAAAAAAAA",
"spaceHistoryState": "HISTORY_ON",
"type": "ROOM",
"threaded": true
}
}
對話方塊的資訊卡點擊次數
當使用者與對話方塊互動時,CARD_CLICKED
互動事件的酬載會包含下列額外欄位:
isDialogEvent
:設為true
,表示涉及對話方塊的互動事件。DialogEventType
:與對話方塊的互動類型,包括使用者開啟、提交或取消對話方塊。
以下 JSON 範例顯示 CARD_CLICKED
互動事件的要求主體部分。在此範例中,使用者已點選對話方塊中的按鈕,將資訊提交到 Chat 應用程式:
{
"type": "CARD_CLICKED",
...
"isDialogEvent": true,
"dialogEventType": "SUBMIT_DIALOG",
}
相關主題
如要瞭解如何處理互動事件的酬載並傳回回應,請參閱下列指南: