本指南介绍了如何接收和阅读用户输入的信息 卡片消息 和 对话框。 用户可以输入 Chat 应用接收、读取和响应的数据 目标。允许用户输入信息的微件包括:
TextInput
适用于自由格式文本条目,还支持建议。SelectionInput
用于列表项和菜单,如复选框、单选按钮和下拉菜单。DateTimePicker
。
使用卡片构建器设计和预览聊天应用的 JSON 卡片消息:
打开卡片制作工具接收用户的数据输入可让 Chat 应用执行诸多操作,例如 以下:
- 更新客户服务支持请求。
- 创建工作单。
- 使用 Web 服务进行身份验证。
前提条件
Node.js
一款已启用互动功能的 Google Chat 应用。要创建 交互式 Chat 应用,请完成此快速入门。
Apps 脚本
一款已启用互动功能的 Google Chat 应用。要创建 交互式聊天应用,请完成此快速入门。
Python
一款已启用互动功能的 Google Chat 应用。要创建 交互式 Chat 应用,请完成此快速入门。
接收数据的工作原理
Chat 应用以
对话框或卡片消息。在此示例中,一个对话框要求用户输入
使用
TextInput
和
SelectionInput
微件:
完成后,Chat 应用会接收 以 JSON 格式在对话框中输入的用户, 互动事件,其中:
EventType
为CARD_CLICKED
。DialogEventType
为SUBMIT_DIALOG
(仅适用于对话框)。
要获取有关用户输入的内容的数据,请使用
Event.common.formInputs
字段。formInputs
字段是一个映射,其中键是
分配给每个微件的字符串 ID 和值表示
每个 widget。不同的对象代表不同的输入数据类型。对于
示例,
Event.common.formInputs.stringInputs
表示字符串输入。
您的应用程序可以在 访问第一个用户输入的值,
event.common.formInputs.NAME.stringInputs.value[0]
,
其中 NAME
是 name
TextInput
widget。
从卡片接收数据
<ph type="x-smartling-placeholder">
当用户在卡片消息中输入数据时,您的 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
值。如果没有,
app 会返回一个错误。如果存在,应用会确认收到表单数据
并关闭对话框。
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 脚本
此示例通过返回 卡片 JSON。 您还可以使用 Apps 脚本卡片服务。
/**
* 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 界面 不会显示任何错误消息,但 Chat 应用或 卡片会产生意外结果;例如,卡片消息 。
虽然 Chat 界面中可能不会显示错误消息, 提供描述性错误消息和日志数据,以帮助您修正错误 启用 Chat 应用的错误日志记录时。如需观看方面的帮助, 请参阅 排查并修正 Google Chat 错误。