本頁面說明 Google Chat 應用程式可從 Google Chat 接收的互動事件類型。
如要設定 Chat 應用程式來接收互動事件,請參閱「接收及回應與 Chat 應用程式的互動」。
互動事件格式
使用者可以透過許多方式與 Chat 應用程式互動。Google Chat 會針對每種互動類型傳送不同類型的互動事件:
- 訊息:使用者傳送 Chat 應用程式訊息,或是在聊天室中叫用 Chat 應用程式。
- 已新增至聊天室:使用者將 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 專用應用程式時,使用者無法解除安裝。如要進一步瞭解管理員安裝的即時通訊應用程式,請參閱 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 應用程式已從聊天室中移除。即時通訊應用程式不會回應這個事件的訊息,因為這類應用程式已遭移除。
以下 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",
}
應用程式首頁訊息
這項互動事件表示使用者已透過您的 Chat 應用程式開啟即時訊息,並收到 Chat 應用程式首頁訊息。
以下 JSON 範例顯示 APP_HOME
互動事件的要求主體:
{
"chat": {
"type": "APP_HOME",
"user": {
"name": "users/12345678901234567890",
"type": "HUMAN",
"email": "izumi@example.com",
"domainId": "ABCDEFG"
},
"space": {
"name": "spaces/AAAAAAAAAAA",
"singleUserBotDm": true,
"spaceType": "DIRECT_MESSAGE"
}
},
"commonEventObject": {
"invokedFunction": "onAppHome",
"userLocale": "en",
"hostApp": "CHAT"
}
}
透過應用程式首頁訊息提交表單
這項互動事件表示使用者透過 Chat 應用程式的主畫面訊息提交了表單資訊。
以下 JSON 範例顯示 SUBMIT_FORM
互動事件的要求主體:
{
"commonEventObject": {
"userLocale": "en",
"invokedFunction": "onSubmitFunction",
"formInputs": {
"username": {
"": {
"stringInputs": {
"value": [
"Ira"
]
}
}
}
},
"hostApp": "CHAT"
},
"chat": {
"type": "SUBMIT_FORM",
"space": {
"name": "spaces/AAAAAAAAAAA",
"spaceType": "DIRECT_MESSAGE",
"singleUserBotDm": true
},
"user": {
"type": "HUMAN",
"name": "123456789"
}
}
}
相關主題
如要瞭解如何處理互動事件的酬載並傳回回應,請參閱下列指南: