หน้านี้ได้รับการแปลโดย Cloud Translation API

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

หน้านี้อธิบายวิธีที่แอป Google Chat สามารถเปิดกล่องโต้ตอบ เพื่อแสดงอินเทอร์เฟซผู้ใช้ (UI) และตอบสนองต่อผู้ใช้

กล่องโต้ตอบคืออินเทอร์เฟซแบบการ์ดในหน้าต่าง ซึ่งเปิดจากพื้นที่ใน Chat หรือข้อความ กล่องโต้ตอบและเนื้อหาของกล่องโต้ตอบจะแสดงต่อผู้ใช้ที่เปิดกล่องโต้ตอบเท่านั้น

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

ข้อกำหนดเบื้องต้น

HTTP

ส่วนเสริมของ Google Workspace ที่ขยายการทำงานของ Google Chat หากต้องการสร้าง ให้ทำตามคู่มือเริ่มต้นฉบับย่อของ HTTP

Apps Script

ส่วนเสริมของ Google Workspace ที่ขยายการทำงานของ Google Chat หากต้องการสร้าง ให้ทำตามการเริ่มต้นใช้งาน Apps Script อย่างรวดเร็ว

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

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

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

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

ทริกเกอร์คำขอ Dialog

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

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

ตอบกลับคำสั่ง หากต้องการทริกเกอร์คำขอจากคำสั่ง คุณต้องเลือกช่องทำเครื่องหมายเปิดกล่องโต้ตอบเมื่อกำหนดค่าคำสั่ง
ตอบสนองต่อการคลิกปุ่มในข้อความ ไม่ว่าจะอยู่ในส่วนของการ์ดหรือที่ด้านล่างของข้อความ หากต้องการทริกเกอร์คำขอจากปุ่มในข้อความ ให้กำหนดค่าการดำเนินการของonClick ปุ่มโดยตั้งค่า interaction เป็น OPEN_DIALOG

ปุ่มที่เรียกกล่องโต้ตอบ — **รูปที่ 2**: แอป Chat ส่งข้อความที่แจ้งให้ผู้ใช้ใช้คำสั่ง `/addContact` Slash
ข้อความยังมีปุ่มที่ผู้ใช้คลิกเพื่อเรียกใช้คำสั่งได้ด้วย

JSON ต่อไปนี้แสดงวิธีทริกเกอร์คำขอ Dialog จากปุ่มใน ข้อความการ์ด หากต้องการเปิดกล่องโต้ตอบ ให้ตั้งค่าฟิลด์ 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 หากต้องการดูวิธีรวบรวมและประมวลผลข้อมูลในกล่องโต้ตอบ โปรดดูรวบรวมและประมวลผลข้อมูลจากผู้ใช้ Google Chat

แอป 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

ตัวอย่างนี้จะส่งข้อความการ์ดโดยการส่งคืน 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 แสดงถึงวิดเจ็ตอินพุตแบบฟอร์มอื่นๆ

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

เมื่อผู้ใช้คลิกปุ่มส่งในกล่องโต้ตอบ แอป Chat จะดำเนินการที่เชื่อมโยงและระบุออบเจ็กต์เหตุการณ์โดยตั้งค่า 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 ตั้งค่าเป็นข้อความใหม่ ตัวอย่างเช่น หากต้องการปิดกล่องโต้ตอบ และส่งข้อความ ให้ส่งคืนค่าต่อไปนี้

{ "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