คู่มือนี้อธิบายวิธีรับและอ่านข้อมูลที่ผู้ใช้ป้อนในข้อความการ์ดและกล่องโต้ตอบ ผู้ใช้สามารถป้อนข้อมูลที่แอป Chat ได้รับ อ่าน และตอบกลับ วิดเจ็ตที่ให้ผู้ใช้ป้อนข้อมูลได้มีดังนี้
TextInput
สำหรับการป้อนข้อความรูปแบบอิสระที่รองรับคำแนะนำด้วยSelectionInput
สำหรับรายการและเมนู เช่น ช่องทำเครื่องหมาย ปุ่มตัวเลือก และเมนูแบบเลื่อนลงDateTimePicker
สำหรับรายการวันที่และเวลา
ใช้เครื่องมือสร้างการ์ดเพื่อออกแบบและแสดงตัวอย่างข้อความการ์ด JSON สำหรับแอป Chat ดังนี้
เปิดเครื่องมือสร้างการ์ดการรับข้อมูลจากผู้ใช้ช่วยให้แอป Chat ทำสิ่งต่างๆ ต่อไปนี้ได้
- อัปเดตเคสฝ่ายบริการลูกค้า
- สร้างใบสั่งงาน
- ตรวจสอบสิทธิ์ด้วยบริการเว็บ
วิธีการทำงานของการรับข้อมูล
แอป Chat จะแสดงข้อมูลแก่ผู้ใช้เป็นกล่องโต้ตอบหรือข้อความการ์ด ในตัวอย่างนี้ กล่องโต้ตอบจะขอให้ผู้ใช้ป้อนข้อมูลเกี่ยวกับรายชื่อติดต่อโดยใช้วิดเจ็ต TextInput
และ SelectionInput
เมื่อเสร็จแล้ว แอป Chat จะได้รับข้อมูลที่ผู้ใช้ป้อนในกล่องโต้ตอบในรูปแบบ JSON และเหตุการณ์การโต้ตอบซึ่งมีลักษณะดังนี้
EventType
คือCARD_CLICKED
DialogEventType
คือSUBMIT_DIALOG
(สำหรับกล่องโต้ตอบเท่านั้น)
หากต้องการดูข้อมูลเกี่ยวกับสิ่งที่ผู้ใช้ป้อน ให้ใช้ช่อง Event.common.formInputs
ในเพย์โหลดเหตุการณ์ ช่อง formInputs
คือแผนที่ซึ่งคีย์คือรหัสสตริงที่กำหนดให้กับวิดเจ็ตแต่ละรายการและค่าที่แสดงข้อมูลที่ผู้ใช้ป้อนสำหรับวิดเจ็ตแต่ละรายการ ออบเจ็กต์ต่างๆ แสดงถึงประเภทข้อมูลอินพุตที่ต่างกัน ตัวอย่างเช่น 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
}
}
ตอบสนองต่อข้อมูลที่รวบรวมจากข้อความการ์ดหรือกล่องโต้ตอบ
หลังจากได้รับข้อมูลจากข้อความหรือกล่องโต้ตอบของการ์ดแล้ว แอป Chat จะตอบสนองด้วยการรับทราบข้อความหรือส่งกลับข้อผิดพลาด ซึ่งทั้ง 2 อย่างนี้จะทำโดยการส่งกลับ 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 ก็ได้
/**
* 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 จะแสดงข้อความว่า "เกิดข้อผิดพลาด" หรือ "ไม่สามารถดำเนินการตามคำขอของคุณ" บางครั้ง UI ของ Chat ไม่แสดงข้อความแสดงข้อผิดพลาด แต่แอปหรือการ์ด Chat จะให้ผลลัพธ์ที่ไม่คาดคิด เช่น ข้อความการ์ดอาจไม่ปรากฏ
แม้ว่าข้อความแสดงข้อผิดพลาดอาจไม่แสดงใน UI ของ Chat แต่ก็จะมีข้อความแสดงข้อผิดพลาดที่สื่อความหมายและข้อมูลบันทึกพร้อมช่วยคุณแก้ไขข้อผิดพลาดเมื่อเปิดการบันทึกข้อผิดพลาดสำหรับแอป Chat ไว้ หากต้องการความช่วยเหลือในการดู แก้ไขข้อบกพร่อง และการแก้ไขข้อผิดพลาด โปรดดูหัวข้อแก้ปัญหาและแก้ไขข้อผิดพลาดของ Google Chat