เปิดกล่องโต้ตอบแบบอินเทอร์แอกทีฟ

หน้านี้อธิบายวิธีที่แอป 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 อย่างรวดเร็ว

เปิดกล่องโต้ตอบ

กล่องโต้ตอบที่มีวิดเจ็ตต่างๆ
รูปที่ 1: แอป Chat ที่เปิดกล่องโต้ตอบเพื่อรวบรวมข้อมูลติดต่อ

ส่วนนี้จะอธิบายวิธีตอบกลับและตั้งค่ากล่องโต้ตอบโดยทําดังนี้

  1. ทริกเกอร์คําขอกล่องโต้ตอบจากการโต้ตอบของผู้ใช้
  2. จัดการคําขอโดยกลับไปที่กล่องโต้ตอบ
  3. หลังจากผู้ใช้ส่งข้อมูลแล้ว ให้ประมวลผลข้อมูลที่ส่งโดยปิดกล่องโต้ตอบหรือแสดงกล่องโต้ตอบอื่น

ทริกเกอร์คําขอกล่องโต้ตอบ

แอป Chat สามารถเปิดกล่องโต้ตอบเพื่อตอบสนองต่อการโต้ตอบของผู้ใช้เท่านั้น เช่น คำสั่งเครื่องหมายทับหรือการคลิกปุ่มจากข้อความในการ์ด

หากต้องการตอบกลับผู้ใช้ด้วยกล่องโต้ตอบ แอป Chat จะต้องสร้างการโต้ตอบที่ทริกเกอร์คำขอกล่องโต้ตอบ เช่น ต่อไปนี้

  • ตอบกลับคำสั่งเครื่องหมายทับ หากต้องการทริกเกอร์คําขอจากคําสั่งเครื่องหมายทับ คุณต้องเลือกช่องทําเครื่องหมายเปิดกล่องโต้ตอบเมื่อกําหนดค่าคําสั่ง
  • ตอบสนองต่อการคลิกปุ่มในข้อความ ไม่ว่าจะเป็นส่วนหนึ่งของการ์ดหรือที่ด้านล่างของข้อความ หากต้องการทริกเกอร์คำขอจากปุ่มในข้อความ ให้กำหนดค่าการดำเนินการ onClick ของปุ่มโดยตั้งค่า interaction เป็น OPEN_DIALOG
ปุ่มที่เรียกให้กล่องโต้ตอบแสดงขึ้น
รูปที่ 2: แอป Chat ส่งข้อความแจ้งให้ผู้ใช้ใช้คำสั่ง /addContact ทับเครื่องหมายทับ
ข้อความยังมีปุ่มที่ผู้ใช้คลิกเพื่อเรียกใช้คําสั่งได้ด้วย

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 ออบเจ็กต์ที่มีการดำเนินการอย่างใดอย่างหนึ่งต่อไปนี้

แก้ปัญหา

เมื่อแอป Google Chat หรือการ์ดแสดงข้อผิดพลาด อินเทอร์เฟซของ Chat จะแสดงข้อความว่า "เกิดข้อผิดพลาด" หรือ "ดำเนินการตามคำขอของคุณไม่ได้" บางครั้ง UI ของ Chat ไม่แสดงข้อความแสดงข้อผิดพลาด แต่แอป Chat หรือการ์ดให้ผลลัพธ์ที่ไม่คาดคิด เช่น ข้อความการ์ดอาจไม่ปรากฏ

แม้ว่าข้อความแสดงข้อผิดพลาดอาจไม่แสดงใน UI ของ Chat แต่ข้อความแสดงข้อผิดพลาดที่อธิบายรายละเอียดและข้อมูลบันทึกจะพร้อมให้ใช้งานเพื่อช่วยคุณแก้ไขข้อผิดพลาดเมื่อเปิดการบันทึกข้อผิดพลาดสำหรับแอป Chat หากต้องการความช่วยเหลือในการดู การแก้ไขข้อบกพร่อง และการแก้ไขข้อผิดพลาด โปรดดูแก้ปัญหาและแก้ไขข้อผิดพลาดของ Google Chat