หน้านี้อธิบายวิธีที่แอป Google Chat เปิดกล่องโต้ตอบเพื่อแสดงอินเทอร์เฟซผู้ใช้ (UI) และตอบสนองต่อผู้ใช้
ใน Google Chat ส่วนเสริมจะปรากฏต่อผู้ใช้เป็นแอป Google Chat ดูข้อมูลเพิ่มเติมได้ที่ภาพรวมการขยาย Google Chat
กล่องโต้ตอบคืออินเทอร์เฟซแบบการ์ดที่มีหน้าต่างซึ่งเปิดจากพื้นที่ทำงานหรือข้อความใน Chat กล่องโต้ตอบและเนื้อหาของกล่องจะแสดงต่อผู้ใช้ที่เปิดเท่านั้น
แอปแชทสามารถใช้กล่องโต้ตอบเพื่อขอและรวบรวมข้อมูลจากผู้ใช้ Chat รวมถึงแบบฟอร์มแบบหลายขั้นตอน ดูรายละเอียดเพิ่มเติมเกี่ยวกับการสร้างอินพุตแบบฟอร์มได้ที่รวบรวมและประมวลผลข้อมูลจากผู้ใช้
ข้อกำหนดเบื้องต้น
Node.js
ส่วนเสริมของ Google Workspace ที่ขยายความสามารถของ Google Chat หากต้องการสร้าง ให้ทำตามการเริ่มต้นใช้งาน HTTP ฉบับย่อ
Apps Script
ส่วนเสริมของ Google Workspace ที่ขยายความสามารถของ Google Chat หากต้องการสร้าง โปรดทำตามการเริ่มต้นใช้งาน Apps Script อย่างรวดเร็ว
เปิดกล่องโต้ตอบ
ส่วนนี้จะอธิบายวิธีตอบกลับและตั้งค่ากล่องโต้ตอบโดยทําดังนี้
- ทริกเกอร์คําขอกล่องโต้ตอบจากการโต้ตอบของผู้ใช้
- จัดการคําขอโดยกลับไปที่กล่องโต้ตอบ
- หลังจากผู้ใช้ส่งข้อมูลแล้ว ให้ประมวลผลข้อมูลที่ส่งโดยปิดกล่องโต้ตอบหรือแสดงกล่องโต้ตอบอื่น
ทริกเกอร์คําขอกล่องโต้ตอบ
แอป Chat สามารถเปิดกล่องโต้ตอบเพื่อตอบสนองต่อการโต้ตอบของผู้ใช้เท่านั้น เช่น คำสั่งเครื่องหมายทับหรือการคลิกปุ่มจากข้อความในการ์ด
หากต้องการตอบกลับผู้ใช้ด้วยกล่องโต้ตอบ แอป Chat จะต้องสร้างการโต้ตอบที่ทริกเกอร์คำขอกล่องโต้ตอบ เช่น ต่อไปนี้
- ตอบกลับคำสั่งเครื่องหมายทับ หากต้องการทริกเกอร์คําขอจากคําสั่งเครื่องหมายทับ คุณต้องเลือกช่องทําเครื่องหมายเปิดกล่องโต้ตอบเมื่อกําหนดค่าคําสั่ง
- ตอบสนองต่อการคลิกปุ่มในข้อความ ไม่ว่าจะเป็นส่วนหนึ่งของการ์ดหรือที่ด้านล่างของข้อความ หากต้องการทริกเกอร์คำขอจากปุ่มในข้อความ ให้กำหนดค่าการดำเนินการ
onClick
ของปุ่มโดยตั้งค่าinteraction
เป็นOPEN_DIALOG
JSON ต่อไปนี้แสดงวิธีเรียกใช้คําขอกล่องโต้ตอบจากปุ่มในข้อความการ์ด หากต้องการเปิดกล่องโต้ตอบ ให้ตั้งค่าช่อง
onClick.action.interaction
ของปุ่มเป็น OPEN_DIALOG
{
"buttonList": { "buttons": [{
"text": "BUTTON_TEXT",
"onClick": { "action": {
"function": "ACTION_FUNCTION",
"interaction": "OPEN_DIALOG"
}}
}]}
}
โดยที่ BUTTON_TEXT คือข้อความที่แสดงในปุ่ม และ ACTION_FUNCTION คือฟังก์ชันที่ทำงานเพื่อเปิดกล่องโต้ตอบเริ่มต้น
เปิดกล่องโต้ตอบเริ่มต้น
เมื่อผู้ใช้เรียกคําขอกล่องโต้ตอบ แอป Chat ของคุณจะได้รับออบเจ็กต์เหตุการณ์ที่มีเพย์โหลดที่ระบุออบเจ็กต์ dialogEventType
เป็น REQUEST_DIALOG
หากต้องการเปิดกล่องโต้ตอบ แอป Chat สามารถตอบสนองคำขอได้โดยแสดงออบเจ็กต์ RenderActions
ที่มีการนำทาง pushCard
เพื่อแสดงการ์ด การ์ดควรมีองค์ประกอบอินเทอร์เฟซผู้ใช้ (UI) ใดก็ได้ รวมถึงวิดเจ็ต sections[]
อย่างน้อย 1 รายการ หากต้องการรวบรวมข้อมูลจากผู้ใช้ คุณสามารถระบุวิดเจ็ตการป้อนข้อมูลแบบฟอร์มและวิดเจ็ตปุ่ม ดูข้อมูลเพิ่มเติมเกี่ยวกับการออกแบบอินพุตแบบฟอร์มได้ที่รวบรวมและประมวลผลข้อมูลจากผู้ใช้
JSON ต่อไปนี้แสดงวิธีที่แอป Chat ส่งการตอบกลับที่เปิดกล่องโต้ตอบ
{
"action": { "navigations": [{ "pushCard": { "sections": [{ "widgets": [{
WIDGETS,
{ "buttonList": { "buttons": [{
"text": "BUTTON_TEXT",
"onClick": {
"action": { "function": "ACTION_FUNCTION" }
}
}]}}
}]}]}}]}
}
โดยที่ BUTTON_TEXT คือข้อความที่แสดงในปุ่ม (เช่น Next
หรือ Submit
) WIDGETS แสดงถึงวิดเจ็ตอินพุตแบบฟอร์มอย่างน้อย 1 รายการ และ ACTION_FUNCTION คือฟังก์ชันการเรียกกลับของการดำเนินการ ซึ่งจะทำงานเมื่อผู้ใช้คลิกปุ่ม
จัดการการส่งกล่องโต้ตอบ
เมื่อผู้ใช้คลิกปุ่มที่ส่งกล่องโต้ตอบ แอปแชทของคุณจะได้รับออบเจ็กต์เหตุการณ์ที่มีออบเจ็กต์ ButtonClickedPayload
ในเพย์โหลด dialogEventType
มีการตั้งค่าเป็น SUBMIT_DIALOG
แอป Chat ของคุณต้องจัดการออบเจ็กต์เหตุการณ์โดยทำอย่างใดอย่างหนึ่งต่อไปนี้
- แสดงกล่องโต้ตอบอื่นเพื่อป้อนข้อมูลการ์ดหรือแบบฟอร์มอื่น
- ปิดกล่องโต้ตอบหลังจากตรวจสอบข้อมูลที่ผู้ใช้ส่ง และส่งข้อความยืนยัน (ไม่บังคับ)
ไม่บังคับ: แสดงกล่องโต้ตอบอื่น
หลังจากผู้ใช้ส่งกล่องโต้ตอบแรกแล้ว แอป Chat จะแสดงกล่องโต้ตอบเพิ่มเติมอย่างน้อย 1 รายการเพื่อช่วยผู้ใช้ตรวจสอบข้อมูลก่อนส่ง กรอกแบบฟอร์มแบบหลายขั้นตอน หรือป้อนข้อมูลแบบฟอร์มแบบไดนามิก
แอป Chat จะประมวลผลข้อมูลที่ผู้ใช้ป้อนโดยจัดการข้อมูลในออบเจ็กต์ commonEventObject.formInputs
ของเหตุการณ์ ดูข้อมูลเพิ่มเติมเกี่ยวกับการดึงค่าจากวิดเจ็ตอินพุตได้ที่หัวข้อรวบรวมและประมวลผลข้อมูลจากผู้ใช้
หากต้องการติดตามข้อมูลที่ผู้ใช้ป้อนจากกล่องโต้ตอบแรก คุณต้องเพิ่มพารามิเตอร์ลงในปุ่มที่เปิดกล่องโต้ตอบถัดไป โปรดดูรายละเอียดที่หัวข้อโอนข้อมูลไปยังการ์ดอื่น
ในตัวอย่างนี้ แอป Chat จะเปิดกล่องโต้ตอบแรกซึ่งนําไปยังกล่องโต้ตอบที่ 2 เพื่อการยืนยันก่อนส่ง
Node.js
/**
* Google Cloud Function that handles all Google Workspace Add On events for
* the contact manager app.
*
* @param {Object} req Request sent from Google Chat space
* @param {Object} res Response to send back
*/
exports.contactManager = function contactManager(req, res) {
const chatEvent = req.body.chat;
// Handle MESSAGE events
if(chatEvent.messagePayload) {
return res.send(handleMessage(req.body));
// Handle button clicks
} else if(chatEvent.buttonClickedPayload) {
switch(req.body.commonEventObject.parameters.actionName) {
case "openInitialDialog":
return res.send(openInitialDialog(req.body));
case "openConfirmationDialog":
return res.send(openConfirmationDialog(req.body));
case "submitDialog":
return res.send(submitDialog(req.body));
}
}
};
/**
* Responds to a message in Google Chat.
*
* @param {Object} event The event object from the Google Workspace Add-on.
* @return {Object} response that handles dialogs.
*/
function handleMessage(event) {
// Reply with a message that contains a button to open the initial dialog
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
text: "To add a contact, use the `ADD CONTACT` button below.",
accessoryWidgets: [{ buttonList: { buttons: [{
text: "ADD CONTACT",
onClick: { action: {
// Use runtime environment variable set with self URL
function: process.env.BASE_URL,
parameters: [{ key: "actionName", value: "openInitialDialog" }],
interaction: "OPEN_DIALOG"
}}
}]}}]
}}}}};
}
/**
* Opens the initial step of the dialog that lets users add contact details.
*
* @param {Object} event The event object from the Google Workspace Add-on.
* @return {Object} open the dialog.
*/
function openInitialDialog(event) {
return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
textInput: {
name: "contactName",
label: "First and last name",
type: "SINGLE_LINE"
}},
WIDGETS, {
buttonList: { buttons: [{
text: "NEXT",
onClick: { action: {
// Use runtime environment variable set with self URL
function: process.env.BASE_URL,
parameters: [{ key: "actionName", value: "openConfirmationDialog" }]
}}
}]}}
]}]}}]}};
}
/**
* Opens the second step of the dialog that lets users confirm details.
*
* @param {Object} event The event object from the Google Workspace Add-on.
* @return {Object} update the dialog.
*/
function openConfirmationDialog(event) {
// Retrieve the form input values
const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
// Display the input values for confirmation
textParagraph: { text: "<b>Name:</b> " + name }},
WIDGETS, {
buttonList: { buttons: [{
text: "SUBMIT",
onClick: { action: {
// Use runtime environment variable set with self URL
function: process.env.BASE_URL,
parameters: [{
key: "actionName", value: "submitDialog" }, {
// Pass input values as parameters for last dialog step (submission)
key: "contactName", value: name
}]
}}
}]}}]
}]}}]}};
}
Apps Script
ตัวอย่างนี้จะส่งข้อความการ์ดโดยแสดงcard JSON นอกจากนี้ คุณยังใช้บริการการ์ด Apps Script ได้ด้วย
/**
* Responds to a message in Google Chat.
*
* @param {Object} event The event object from the Google Workspace Add-on.
* @return {Object} response that handles dialogs.
*/
function onMessage(event) {
// Reply with a message that contains a button to open the initial dialog
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
text: "To add a contact, use the `ADD CONTACT` button below.",
accessoryWidgets: [{ buttonList: { buttons: [{
text: "ADD CONTACT",
onClick: { action: {
function: "openInitialDialog",
interaction: "OPEN_DIALOG"
}}
}]}}]
}}}}};
}
/**
* Opens the initial step of the dialog that lets users add contact details.
*
* @param {Object} event The event object from the Google Workspace Add-on.
* @return {Object} open the dialog.
*/
function openInitialDialog(event) {
return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
textInput: {
name: "contactName",
label: "First and last name",
type: "SINGLE_LINE"
}},
WIDGETS, {
buttonList: { buttons: [{
text: "NEXT",
onClick: { action: { function : "openConfirmationDialog" }}
}]}}
]}]}}]}};
}
/**
* Opens the second step of the dialog that lets users confirm details.
*
* @param {Object} event The event object from the Google Workspace Add-on.
* @return {Object} update the dialog.
*/
function openConfirmationDialog(event) {
// Retrieve the form input values
const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
// Display the input values for confirmation
textParagraph: { text: "<b>Name:</b> " + name }},
WIDGETS, {
buttonList: { buttons: [{
text: "SUBMIT",
onClick: { action: {
function: "submitDialog",
// Pass input values as parameters for last dialog step (submission)
parameters: [{ key: "contactName", value: name }]
}}
}]}}]
}]}}]}};
}
โดยที่ WIDGETS แสดงถึงวิดเจ็ตอินพุตแบบฟอร์มอื่นๆ
ปิดกล่องโต้ตอบ
เมื่อผู้ใช้คลิกปุ่มส่งในกล่องโต้ตอบ แอปแชทจะดำเนินการที่เกี่ยวข้องและระบุออบเจ็กต์เหตุการณ์โดยตั้งค่า buttonClickedPayload
เป็นค่าต่อไปนี้
isDialogEvent
คือtrue
dialogEventType
คือSUBMIT_DIALOG
แอป Chat ควรแสดงผลออบเจ็กต์ RenderActions
ที่มีการตั้งค่า EndNavigation
เป็น CLOSE_DIALOG
ไม่บังคับ: แสดงการแจ้งเตือน
เมื่อปิดกล่องโต้ตอบ คุณยังแสดงการแจ้งเตือนข้อความได้ด้วย
หากต้องการแสดงการแจ้งเตือน ให้แสดงออบเจ็กต์ RenderActions
ที่มีการตั้งค่าช่อง notification
ตัวอย่างต่อไปนี้จะตรวจสอบว่าพารามิเตอร์ถูกต้องและปิดกล่องโต้ตอบด้วยการแจ้งเตือนแบบข้อความโดยขึ้นอยู่กับผลลัพธ์
Node.js
/**
* Handles submission and closes the dialog.
*
* @param {Object} event The event object from the Google Workspace Add-on.
* @return {Object} close the dialog with a status in text notification.
*/
function submitDialog(event) {
// Validate the parameters.
if (!event.commonEventObject.parameters["contactName"]) {
return { action: {
navigations: [{ endNavigation: "CLOSE_DIALOG"}],
notification: { text: "Failure, the contact name was missing!" }
}};
}
return { action: {
navigations: [{ endNavigation: "CLOSE_DIALOG"}],
notification: { text: "Success, the contact was added!" }
}};
}
Apps Script
/**
* Handles submission and closes the dialog.
*
* @param {Object} event The event object from the Google Workspace Add-on.
* @return {Object} close the dialog with a status in text notification.
*/
function submitDialog(event) {
// Validate the parameters.
if (!event.commonEventObject.parameters["contactName"]) {
return { action: {
navigations: [{ endNavigation: "CLOSE_DIALOG"}],
notification: { text: "Failure, the contact name was missing!" }
}};
}
return { action: {
navigations: [{ endNavigation: "CLOSE_DIALOG"}],
notification: { text: "Success, the contact was added!" }
}};
}
โปรดดูรายละเอียดเกี่ยวกับการส่งพารามิเตอร์ระหว่างกล่องโต้ตอบที่หัวข้อโอนข้อมูลไปยังการ์ดอื่น
ไม่บังคับ: ส่งข้อความยืนยัน
เมื่อปิดกล่องโต้ตอบ คุณจะส่งข้อความใหม่หรืออัปเดตข้อความที่มีอยู่ได้ด้วย
หากต้องการส่งข้อความใหม่ ให้แสดงผลออบเจ็กต์ DataActions
ที่มีการตั้งค่าช่อง CreateMessageAction
ด้วยข้อความใหม่ เช่น หากต้องการปิดกล่องโต้ตอบและส่ง SMS ให้แสดงผลลัพธ์ต่อไปนี้
{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {
"text": "Your information has been submitted."
}}}}}
หากต้องการอัปเดตข้อความหลังจากที่ผู้ใช้ส่งกล่องโต้ตอบ ให้แสดงผลDataActions
ออบเจ็กต์ที่มีการดำเนินการอย่างใดอย่างหนึ่งต่อไปนี้
UpdateMessageAction
: อัปเดตข้อความที่ส่งโดยแอป Chat เช่น ข้อความที่ผู้ใช้ส่งคำขอกล่องโต้ตอบUpdateInlinePreviewAction
: อัปเดตการ์ดจากตัวอย่างลิงก์
แก้ปัญหา
เมื่อแอป Google Chat หรือการ์ดแสดงข้อผิดพลาด อินเทอร์เฟซของ Chat จะแสดงข้อความว่า "เกิดข้อผิดพลาด" หรือ "ดำเนินการตามคำขอของคุณไม่ได้" บางครั้ง UI ของ Chat ไม่แสดงข้อความแสดงข้อผิดพลาด แต่แอป Chat หรือการ์ดให้ผลลัพธ์ที่ไม่คาดคิด เช่น ข้อความการ์ดอาจไม่ปรากฏ
แม้ว่าข้อความแสดงข้อผิดพลาดอาจไม่แสดงใน UI ของ Chat แต่ข้อความแสดงข้อผิดพลาดที่อธิบายรายละเอียดและข้อมูลบันทึกจะพร้อมให้ใช้งานเพื่อช่วยคุณแก้ไขข้อผิดพลาดเมื่อเปิดการบันทึกข้อผิดพลาดสำหรับแอป Chat หากต้องการความช่วยเหลือในการดู การแก้ไขข้อบกพร่อง และการแก้ไขข้อผิดพลาด โปรดดูแก้ปัญหาและแก้ไขข้อผิดพลาดของ Google Chat