Hướng dẫn này mô tả cách nhận và đọc thông tin mà người dùng nhập vào tin nhắn thẻ và hộp thoại. Người dùng có thể nhập dữ liệu mà ứng dụng Chat nhận được, đọc và phản hồi. Các tiện ích cho phép người dùng nhập thông tin gồm có:
TextInputđể nhập văn bản dạng tự do cũng hỗ trợ các đề xuất.SelectionInputcho các mục trong danh sách và trình đơn, chẳng hạn như hộp đánh dấu, nút chọn và trình đơn thả xuống.DateTimePickercho các mục nhập ngày và giờ.
Sử dụng Trình tạo thẻ để thiết kế và xem trước thông báo trong thẻ JSON cho ứng dụng nhắn tin:
Mở Trình tạo thẻKhi nhận dữ liệu đầu vào từ người dùng, các ứng dụng trong Chat sẽ có thể làm những việc như sau:
- Cập nhật các trường hợp dịch vụ khách hàng.
- Tạo đơn hàng công việc.
- Xác thực bằng dịch vụ web.
Cách hoạt động của quy trình nhận dữ liệu
Ứng dụng Chat hiển thị thông tin cho người dùng dưới dạng hộp thoại hoặc tin nhắn thẻ. Trong ví dụ này, một hộp thoại yêu cầu người dùng nhập thông tin về một người liên hệ bằng các tiện ích TextInput và SelectionInput:
Khi hoàn tất, ứng dụng Chat sẽ nhận được dữ liệu mà người dùng đã nhập vào hộp thoại ở định dạng JSON và một sự kiện tương tác, trong đó:
EventTypelàCARD_CLICKED.DialogEventTypelàSUBMIT_DIALOG(chỉ dành cho hộp thoại).
Để nhận dữ liệu về dữ liệu mà người dùng đã nhập, hãy sử dụng trường Event.common.formInputs trong tải trọng sự kiện. Trường formInputs là một bản đồ, trong đó các khoá là mã nhận dạng chuỗi được chỉ định cho mỗi tiện ích và các giá trị đại diện cho hoạt động đầu vào của người dùng cho từng tiện ích. Các đối tượng khác nhau đại diện cho các kiểu dữ liệu đầu vào khác nhau. Ví dụ: Event.common.formInputs.stringInputs đại diện cho dữ liệu đầu vào dạng chuỗi.
Ứng dụng của bạn có thể truy cập vào giá trị đầu tiên do người dùng nhập tại event.common.formInputs.NAME.stringInputs.value[0], trong đó NAME là trường name của tiện ích TextInput.
Nhận dữ liệu từ thẻ
Khi người dùng nhập dữ liệu vào tin nhắn thẻ, ứng dụng Chat sẽ nhận được một sự kiện tương tác với ứng dụng Chat, chẳng hạn như ví dụ sau:
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
}
}
Nhận dữ liệu qua hộp thoại
Khi người dùng gửi dữ liệu trong một hộp thoại, ứng dụng Chat sẽ nhận được một sự kiện tương tác khác với ứng dụng Chat, chẳng hạn như ví dụ sau:
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
}
}
Phản hồi dữ liệu được thu thập qua tin nhắn hoặc hộp thoại bằng thẻ
Sau khi nhận được dữ liệu từ tin nhắn hoặc hộp thoại thẻ, ứng dụng Chat sẽ phản hồi bằng cách xác nhận thông báo nhận hoặc bằng cách trả về lỗi, cả hai đều được thực hiện bằng cách trả về một ActionResponse:
- Để xác nhận việc nhận thành công, hãy phản hồi bằng tham số
ActionResponsecó"actionStatus": "OK". - Để trả về lỗi, hãy phản hồi bằng tham số
ActionResponsecó"actionStatus": "ERROR MESSAGE".
Ví dụ:
Ví dụ sau đây sẽ kiểm tra sự hiện diện của giá trị name. Nếu không có, ứng dụng sẽ trả về lỗi. Nếu có, ứng dụng sẽ xác nhận đã nhận dữ liệu biểu mẫu và đóng hộp thoại.
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
Ví dụ này gửi tin nhắn thẻ bằng cách trả về tệp JSON của thẻ. Bạn cũng có thể sử dụng dịch vụ thẻ 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!'
}
}
}
Khắc phục sự cố
Khi ứng dụng Google Chat hoặc thẻ trả về lỗi, giao diện Chat sẽ hiển thị thông báo "Đã xảy ra lỗi." hoặc "Không thể xử lý yêu cầu của bạn". Đôi khi, giao diện người dùng của Chat không hiển thị thông báo lỗi nào, nhưng ứng dụng hoặc thẻ Chat cho ra kết quả không mong muốn; ví dụ: thông báo thẻ có thể không xuất hiện.
Mặc dù thông báo lỗi có thể không hiển thị trong giao diện người dùng Chat, nhưng chúng tôi cung cấp dữ liệu nhật ký và thông báo lỗi mô tả để giúp bạn khắc phục lỗi khi bật tính năng ghi nhật ký lỗi cho các ứng dụng trong Chat. Để được trợ giúp về việc xem, gỡ lỗi và sửa lỗi, hãy xem phần Khắc phục sự cố và sửa lỗi trên Google Chat.