本指南說明如何接收及閱讀使用者輸入的資訊 資訊卡訊息 和 「對話方塊」。 使用者可以輸入 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 錯誤。