本指南說明如何接收及讀取使用者在資訊卡訊息和對話方塊中輸入的資訊。使用者可以輸入 Chat 應用程式接收、讀取及回覆的資料。可讓使用者輸入資訊的小工具包括：
TextInput用於輸入也支援建議的任意形式文字輸入。SelectionInput用於清單項目和選單，例如核取方塊、圓形按鈕和下拉式選單。DateTimePicker用於日期與時間項目。
使用資訊卡建構工具設計及預覽 Chat 應用程式的 JSON 資訊卡訊息：
開啟資訊卡建構工具接收使用者提供的資料後，Chat 應用程式就能執行以下作業：
- 更新客戶服務案件。
- 建立工作任務。
- 使用網路服務進行驗證。
接收資料的運作方式
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 是 TextInput 小工具的 name 欄位。
接收卡片資料
使用者在資訊卡訊息中輸入資料時，您的 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
}
}
回應從資訊卡訊息或對話方塊收集到的資料
收到資訊卡訊息或對話方塊的資料後，Chat 應用程式會回應確認收據或傳回錯誤，兩者都是透過傳回 ActionResponse 完成：
- 如要確認收到成功，請使用包含
"actionStatus": "OK"的ActionResponse參數回應。 - 如要傳回錯誤，請使用含有
"actionStatus": "ERROR MESSAGE"的ActionResponse參數回應。
範例
以下範例會檢查 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 卡片服務。
/**
* 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 應用程式或卡片傳回錯誤，Chat 介面會顯示「發生錯誤」或「無法處理您的要求」的訊息。有時 Chat UI 不會顯示任何錯誤訊息，但即時通訊應用程式或資訊卡產生非預期的結果，例如資訊卡訊息可能不會顯示。
雖然 Chat UI 可能不會顯示錯誤訊息，但我們提供描述性的錯誤訊息和記錄資料，協助您修正啟用 Chat 應用程式錯誤記錄功能時發生的錯誤。如要瞭解如何查看、偵錯及修正錯誤，請參閱「疑難排解及修正 Google Chat 錯誤」。