本指南說明如何接收及閱讀使用者輸入的資訊 資訊卡訊息 和 「對話方塊」。 使用者可以輸入 Chat 擴充應用程式接收、讀取及回覆的資料 。可讓使用者輸入資訊的小工具包括:
TextInput
敬上 ,支援建議的任意形式文字輸入。SelectionInput
敬上 建立清單項目和選單,例如核取方塊、圓形按鈕和下拉式選單。DateTimePicker
敬上 。
您可以使用 Card Builder 設計及預覽即時通訊應用程式的 JSON 資訊卡訊息:
開啟資訊卡建立工具接收使用者輸入內容後,Chat 擴充應用程式就能執行下列操作: 包括:
- 更新客戶服務客服案件。
- 建立工作任務。
- 使用網路服務驗證。
必要條件
Node.js
已啟用互動功能的 Google Chat 應用程式。如要建立 請使用 HTTP 服務互動式即時通訊應用程式,請完成快速入門導覽課程。
Apps Script
已啟用互動功能的 Google Chat 應用程式。如要建立 ,請完成快速入門導覽課程。
Python
已啟用互動功能的 Google Chat 應用程式。如要建立 請使用 HTTP 服務互動式即時通訊應用程式,請完成快速入門導覽課程。
接收資料的運作方式
Chat 應用程式會以
對話方塊或資訊卡訊息。在此範例中,對話方塊要求使用者輸入
某個應用程式的
TextInput
敬上
和
SelectionInput
小工具:
遷移完成後,Chat 應用程式會收到 使用者輸入 JSON 格式的對話方塊 互動事件,其中:
EventType
為CARD_CLICKED
。DialogEventType
敬上 為SUBMIT_DIALOG
(僅適用於對話方塊)。
如要取得使用者輸入內容的相關資料,請使用
Event.common.formInputs
敬上
欄位。formInputs
欄位是對應鍵的對應項目
指派給每個小工具的字串 ID,值代表使用者為
每個小工具不同物件代表不同的輸入資料類型。適用對象
例如
Event.common.formInputs.stringInputs
敬上
代表字串輸入內容
您的應用程式可在以下位置存取使用者輸入的第一個值
event.common.formInputs.NAME.stringInputs.value[0]
,
其中 NAME
是 name
欄位
TextInput
小工具。
接收資訊卡提供的資料
當使用者在資訊卡訊息中輸入資料時, Chat 應用程式收到 Chat 應用程式 互動事件,例如:
JSON
{
"type": enum (EventType),
"eventTime": string,
"threadKey": string,
"message": {
object (Message)
},
"user": {
object (User)
},
"space": {
object (Space)
},
"action": {
object (FormAction)
},
"configCompleteRedirectUrl": string,
"common": {
// Represents user data entered in a card.
"formInputs": {
// Represents user data entered for a specific field in a card.
"NAME": {
// Represents string data entered in a card, like text input fields
// and check boxes.
"stringInputs": {
// An array of strings entered by the user in a card.
"value": [
string
]
}
}
},
"parameters": {
string: string,
...
},
"invokedFunction": string
}
}
接收對話方塊的資料
使用者在對話方塊中提交資料時,您的 Chat 應用程式 收到其他 Chat 應用程式互動事件,例如 範例:
JSON
{
"type": enum (EventType),
"eventTime": string,
"threadKey": string,
"message": {
object (Message)
},
"user": {
object (User)
},
"space": {
object (Space)
},
"action": {
object (FormAction)
},
"configCompleteRedirectUrl": string,
// Indicates that this event is dialog-related.
"isDialogEvent": true,
// Indicates that a user clicked a button, and all data
// they entered in the dialog is included in Event.common.formInputs.
"dialogEventType": "SUBMIT_DIALOG",
"common": {
"userLocale": string,
"hostApp": enum (HostApp),
"platform": enum (Platform),
"timeZone": {
object (TimeZone)
},
// Represents user data entered in a dialog.
"formInputs": {
// Represents user data entered for a specific field in a dialog.
"NAME": {
// Represents string data entered in a dialog, like text input fields
// and check boxes.
"stringInputs": {
// An array of strings entered by the user in a dialog.
"value": [
string
]
}
}
},
"parameters": {
string: string,
...
},
"invokedFunction": string
}
}
回應從資訊卡訊息或對話方塊收集到的資料
收到資訊卡訊息或對話方塊的資料後,
即時通訊應用程式會透過確認接收的方式或
傳回錯誤,兩者都是透過傳回
ActionResponse
:
- 如要確認收到成功,請以
ActionResponse
敬上 含有"actionStatus": "OK"
的參數 - 如要傳回錯誤,請回覆
ActionResponse
敬上 含有"actionStatus": "ERROR MESSAGE"
的參數
範例
以下範例會檢查是否存在 name
值。如果沒有,
應用程式傳回錯誤。如果有,應用程式會確認收到表單資料
然後關閉對話方塊
Node.js
/**
* Checks for a form input error, the absence of
* a "name" value, and returns an error if absent.
* Otherwise, confirms successful receipt of a dialog.
*
* Confirms successful receipt of a dialog.
*
* @param {Object} event the event object from Chat API.
*
* @return {object} open a Dialog in Google Chat.
*/
function receiveDialog(event) {
// Checks to make sure the user entered a name
// in a dialog. If no name value detected, returns
// an error message.
if (event.common.formInputs.WIDGET_NAME.stringInputs.value[0] == "") {
res.json({
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "Don't forget to name your new contact!"
}
}
});
// Otherwise the app indicates that it received
// form data from the dialog. Any value other than "OK"
// gets returned as an error. "OK" is interpreted as
// code 200, and the dialog closes.
} else {
res.json({
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "OK"
}
}
});
}
}
Apps Script
此範例會透過 資訊卡 JSON。 您也可以使用 Apps Script Card 服務。
/**
* Checks for a form input error, the absence of
* a "name" value, and returns an error if absent.
* Otherwise, confirms successful receipt of a dialog.
*
* Confirms successful receipt of a dialog.
*
* @param {Object} event the event object from Chat API.
*
* @return {object} open a Dialog in Google Chat.
*/
function receiveDialog(event) {
// Checks to make sure the user entered a name
// in a dialog. If no name value detected, returns
// an error message.
if (event.common.formInputs.WIDGET_NAME[""].stringInputs.value[0] == "") {
return {
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "Don't forget to name your new contact!"
}
}
};
// Otherwise the app indicates that it received
// form data from the dialog. Any value other than "OK"
// gets returned as an error. "OK" is interpreted as
// code 200, and the dialog closes.
} else {
return {
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "OK"
}
}
};
}
}
Python
def receive_dialog(event: Mapping[str, Any]) -> Mapping[str, Any]:
"""Checks for a form input error, the absence of a "name" value, and returns
an error if absent. Otherwise, confirms successful receipt of a dialog.
Args:
event (Mapping[str, Any]): the event object from Chat API.
Returns:
Mapping[str, Any]: the response.
"""
if common := event.get('common'):
if form_inputs := common.get('formInputs'):
if contact_name := form_inputs.get('WIDGET_NAME'):
if string_inputs := contact_name.get('stringInputs'):
if name := string_inputs.get('value')[0]:
return {
'actionResponse': {
'type': 'DIALOG',
'dialogAction': {
'actionStatus': 'OK'
}
}
}
else:
return {
'actionResponse': {
'type': 'DIALOG',
'dialogAction': {
'actionStatus': 'Don\'t forget to name your new contact!'
}
}
}
疑難排解
Google Chat 應用程式或 card 會傳回錯誤, 即時通訊介面會顯示「發生錯誤」的訊息。 或「無法處理你的要求」。有時使用 Chat UI 不會顯示任何錯誤訊息,但 Chat 應用程式或 資訊卡產生非預期的結果例如資訊卡訊息 顯示。
雖然 Chat UI 中可能不會顯示錯誤訊息, 提供描述性錯誤訊息和記錄資料,協助您修正錯誤 。如需觀看說明, 偵錯及修正錯誤,請參閱 疑難排解並修正 Google Chat 錯誤。