รับและตอบสนองต่อเหตุการณ์การโต้ตอบ

หน้านี้อธิบายวิธีที่แอป Google Chat รับและตอบสนองต่อการโต้ตอบของผู้ใช้ หรือที่เรียกว่าเหตุการณ์การโต้ตอบของแอป Google Chat

หน้านี้จะอธิบายวิธีการทำสิ่งต่อไปนี้

• กำหนดค่าแอป Chat เพื่อรับเหตุการณ์การโต้ตอบ
• ประมวลผลเหตุการณ์การโต้ตอบในโครงสร้างพื้นฐาน
• หากเหมาะสม ให้ตอบกลับเหตุการณ์การโต้ตอบ

หมายเหตุ: คู่มือนี้อธิบายวิธีสร้างแอป Chat แบบอินเทอร์แอกทีฟ โดยใช้เหตุการณ์การโต้ตอบของ Chat API นอกจากนี้ คุณยังสร้างแอป Chat เป็นส่วนเสริมของ Google Workspace ได้ด้วย ดูว่าควรใช้เฟรมเวิร์กใดได้ที่หัวข้อสร้างแอป Google Chat แบบอินเทอร์แอกทีฟ

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

• บัญชี Google Workspace สำหรับธุรกิจหรือองค์กร ที่มีสิทธิ์เข้าถึง Google Chat
• สร้างโปรเจ็กต์ Google Cloud
• กำหนดค่าหน้าจอขอความยินยอม OAuth
• เปิดใช้ Google Chat API

ประเภทของเหตุการณ์การโต้ตอบ

เหตุการณ์การโต้ตอบกับแอป Google Chat แสดงถึงการดำเนินการใดๆ ที่ผู้ใช้ทำเพื่อเรียกใช้หรือโต้ตอบกับแอป Chat เช่น การ @mention แอป Chat หรือการเพิ่มแอปไปยังพื้นที่

เมื่อผู้ใช้โต้ตอบกับแอป Chat Google Chat จะส่งเหตุการณ์การโต้ตอบไปยังแอป Chat ซึ่งแสดงเป็นประเภท Event ใน Chat API แอป Chat สามารถใช้เหตุการณ์เพื่อ ประมวลผลการโต้ตอบ และอาจตอบกลับด้วยข้อความ

สำหรับการโต้ตอบของผู้ใช้แต่ละประเภท Google Chat จะส่งเหตุการณ์การโต้ตอบประเภทต่างๆ ซึ่งจะช่วยให้แอป Chat จัดการเหตุการณ์แต่ละประเภทได้อย่างเหมาะสม ประเภทของเหตุการณ์การโต้ตอบจะแสดงโดยใช้ออบเจ็กต์ eventType

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

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

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

การโต้ตอบของผู้ใช้	eventType	การตอบกลับทั่วไปจากแอป Chat
ผู้ใช้ส่งข้อความถึงแอป Chat เช่น @พูดถึงแอป Chat หรือใช้คำสั่งเครื่องหมายทับ	MESSAGE	แอป Chat จะตอบกลับตามเนื้อหาของ ข้อความ เช่น แอป Chat จะตอบกลับ คำสั่งเครื่องหมายทับ /about ด้วยข้อความที่อธิบายงาน ที่แอป Chat ทำได้
ผู้ใช้เพิ่มแอปใน Chat ลงใน พื้นที่ทำงาน	ADDED_TO_SPACE	แอป Chat จะส่ง ข้อความเริ่มต้นใช้งานที่อธิบายสิ่งที่แอปทำและวิธีที่ผู้ใช้ในพื้นที่ทำงาน โต้ตอบกับแอป
ผู้ใช้นำ แอป Chat ออกจากพื้นที่ทำงาน	REMOVED_FROM_SPACE	แอป Chat จะนำการแจ้งเตือนขาเข้าที่กำหนดค่าไว้สำหรับพื้นที่ทำงาน (เช่น การลบ Webhook) และล้างที่เก็บข้อมูลภายใน
ผู้ใช้คลิกปุ่มในการ์ดจาก ข้อความ กล่องโต้ตอบ หรือหน้าแรกของแอป Chat	CARD_CLICKED	แอป Chat จะประมวลผลและจัดเก็บข้อมูลใดๆ ที่ผู้ใช้ส่งมา หรือแสดงการ์ดอื่น
ผู้ใช้เปิดหน้าแรกของแอป Chat โดยคลิกแท็บหน้าแรกในข้อความแบบ 1:1	APP_HOME	แอป Chat จะแสดงการ์ดแบบคงที่หรือแบบอินเทอร์แอกทีฟ จากหน้าแรก
ผู้ใช้ส่งแบบฟอร์มจากหน้าแรกของแอป Chat	SUBMIT_FORM	แอป Chat จะประมวลผลและจัดเก็บข้อมูลใดๆ ที่ผู้ใช้ส่งมา หรือแสดงการ์ดอื่น
ผู้ใช้เรียกใช้คำสั่งโดยใช้คำสั่งด่วน	APP_COMMAND	แอป Chat จะตอบกลับตามคำสั่งที่เรียกใช้ เช่น แอป Chat จะตอบกลับคำสั่งเกี่ยวกับด้วยข้อความที่อธิบายงานที่แอป Chat ทำได้

หากต้องการดูเหตุการณ์การโต้ตอบที่รองรับทั้งหมด โปรดดูเอกสารประกอบEventTypeอ้างอิง

เหตุการณ์การโต้ตอบจากกล่องโต้ตอบ

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

• ตั้งค่า isDialogEvent เป็น true
• DialogEventType จะระบุว่าการโต้ตอบจะทริกเกอร์ให้กล่องโต้ตอบเปิดขึ้น ส่ง ข้อมูลจากกล่องโต้ตอบ หรือปิดกล่องโต้ตอบ

ตารางต่อไปนี้แสดงการโต้ตอบทั่วไปกับกล่องโต้ตอบ ประเภทเหตุการณ์ของกล่องโต้ตอบที่เกี่ยวข้อง และคำอธิบายเกี่ยวกับวิธีที่แอป Chat ตอบสนองโดยทั่วไป

การโต้ตอบของผู้ใช้กับกล่องโต้ตอบ	ประเภทเหตุการณ์กล่องโต้ตอบ	การตอบกลับทั่วไป
ผู้ใช้ทริกเกอร์คำขอ Dialog เช่น ใช้คำสั่งเครื่องหมายทับ หรือคลิกปุ่มจากข้อความ	REQUEST_DIALOG	แอป Chat จะเปิดกล่องโต้ตอบ
ผู้ใช้ส่งข้อมูลในกล่องโต้ตอบโดยคลิกปุ่ม	SUBMIT_DIALOG	แอป Chat จะไปยังกล่องโต้ตอบอื่น หรือปิดกล่องโต้ตอบเพื่อทําการโต้ตอบให้เสร็จสมบูรณ์
ผู้ใช้ออกจากกล่องโต้ตอบหรือปิดกล่องโต้ตอบก่อนส่งข้อมูล	CANCEL_DIALOG	แอป Chat อาจตอบกลับด้วย ข้อความใหม่ หรืออัปเดตข้อความหรือการ์ดที่ผู้ใช้เปิดกล่องโต้ตอบ ก็ได้

ดูข้อมูลเพิ่มเติมได้ที่หัวข้อเปิดกล่องโต้ตอบแบบอินเทอร์แอกทีฟ

รับเหตุการณ์การโต้ตอบในแอป Chat

ส่วนนี้จะอธิบายวิธีรับและประมวลผลเหตุการณ์การโต้ตอบสำหรับแอป Chat

กำหนดค่าแอป Chat เพื่อรับเหตุการณ์การโต้ตอบ

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

สำหรับฟีเจอร์แบบอินเทอร์แอกทีฟแต่ละรายการที่คุณต้องการสร้าง คุณต้องอัปเดต การกำหนดค่าใน Chat API เพื่อให้ Google Chat ส่ง เหตุการณ์การโต้ตอบที่เกี่ยวข้องไปยังแอป Chat ของคุณได้ โดยทำดังนี้

1. ในคอนโซล Google Cloud ให้ไปที่หน้า Chat API แล้วคลิกหน้าการกำหนดค่า

   ไปที่หน้าการกำหนดค่า Chat API

2. ในส่วนฟีเจอร์แบบอินเทอร์แอกทีฟ ให้ตรวจสอบการตั้งค่าและอัปเดตตาม ฟีเจอร์ที่คุณต้องการสร้าง

   ช่อง	คำอธิบาย
   ฟังก์ชันการทำงาน	ต้องระบุ ชุดฟิลด์ที่กำหนดวิธีที่แอป Chat โต้ตอบกับผู้ใช้ โดยค่าเริ่มต้น ผู้ใช้จะค้นหาและส่งข้อความถึงแอป Chat ได้โดยตรงใน Google Chat เข้าร่วมพื้นที่ทำงานและการสนทนากลุ่ม: ผู้ใช้สามารถเพิ่มแอป Chat ลงในพื้นที่ทำงานและการสนทนากลุ่มได้
   การตั้งค่าการเชื่อมต่อ	ต้องระบุ ปลายทางสำหรับแอป Chat ซึ่งเป็นหนึ่งในรายการต่อไปนี้ URL ปลายทาง HTTP: ปลายทาง HTTPS ที่โฮสต์การติดตั้งใช้งานแอป Chat Apps Script: รหัสการทำให้ใช้งานได้สำหรับโปรเจ็กต์ Apps Script ที่ใช้แอป Chat ชื่อหัวข้อ Cloud Pub/Sub: หัวข้อ Pub/Sub ที่แอป Chat สมัครรับข้อมูลเป็นปลายทาง Dialogflow: ลงทะเบียนแอปใน Chat ด้วยการผสานรวม Dialogflow ดูข้อมูลเพิ่มเติมได้ที่สร้างแอป Dialogflow Google Chat ที่เข้าใจภาษาธรรมชาติ
   คำสั่ง	ไม่บังคับ คำสั่งเครื่องหมายทับและคำสั่งด่วนสำหรับแอป Chat คำสั่งช่วยให้ผู้ใช้ขอให้ดำเนินการหรือใช้ฟีเจอร์ที่เฉพาะเจาะจงของแอป Chat ได้ ดูข้อมูลเพิ่มเติมได้ที่ตอบกลับคำสั่งของแอป Google Chat
   ตัวอย่างลิงก์	ไม่บังคับ รูปแบบ URL ที่แอป Chat รู้จักและแสดงเนื้อหาเพิ่มเติมเมื่อผู้ใช้ส่งลิงก์ ดูข้อมูลเพิ่มเติมได้ที่แสดงตัวอย่างลิงก์
   ระดับการแชร์	ไม่บังคับ บุคคลสูงสุด 5 คน หรือ Google Groups อย่างน้อย 1 กลุ่มที่ดูและติดตั้งแอป Chat ของคุณได้ ใช้ช่องนี้เพื่อทดสอบแอป Chat หรือแชร์แอป Chat กับทีม ดูข้อมูลเพิ่มเติมได้ที่ทดสอบฟีเจอร์แบบอินเทอร์แอกทีฟ

3. คลิกบันทึก เมื่อบันทึกการกำหนดค่าแอป Chat แล้ว แอป Chat จะพร้อมใช้งานสำหรับผู้ใช้ที่ระบุในองค์กร Google Workspace

ตอนนี้แอป Chat ได้รับการกำหนดค่าให้รับเหตุการณ์การโต้ตอบจาก Google Chat แล้ว

จัดการการลองใหม่ของการเรียก HTTP ไปยังบริการของคุณ

หากคำขอ HTTPS ไปยังบริการของคุณไม่สำเร็จ (เช่น หมดเวลา เครือข่ายล้มเหลวชั่วคราว หรือรหัสสถานะ HTTPS ที่ไม่ใช่ 2xx) Google Chat อาจลองส่งอีกครั้ง 2-3 ครั้งภายใน 2-3 นาที (แต่ไม่รับประกัน) ด้วยเหตุนี้ แอป Chat อาจได้รับข้อความเดียวกัน 2-3 ครั้งในบางสถานการณ์ หากคำขอเสร็จสมบูรณ์ แต่แสดงผลเพย์โหลดข้อความที่ไม่ถูกต้อง Google Chat จะไม่ลองส่งคำขออีกครั้ง

ประมวลผลหรือตอบสนองต่อเหตุการณ์การโต้ตอบ

ส่วนนี้อธิบายวิธีที่แอป Google Chat ประมวลผลและตอบกลับเหตุการณ์การโต้ตอบได้

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

หากต้องการตอบกลับแบบซิงโครนัส แอป Chat ต้องตอบกลับภายใน 30 วินาที และต้องโพสต์คำตอบในพื้นที่ทำงานที่มีการโต้ตอบ มิฉะนั้น แอป Chat จะ ตอบกลับแบบไม่พร้อมกัน

สำหรับเหตุการณ์การโต้ตอบแต่ละรายการ แอป Chat จะได้รับเนื้อหาคำขอ ซึ่งเป็นเพย์โหลด JSON ที่แสดงถึงเหตุการณ์ คุณสามารถใช้ ข้อมูลเพื่อประมวลผลการตอบกลับได้ ดูตัวอย่างเพย์โหลดของเหตุการณ์ได้ที่ประเภทของเหตุการณ์การโต้ตอบของแอป Chat

แผนภาพต่อไปนี้แสดงให้เห็นว่าโดยปกติแล้วแอป Google Chat จะประมวลผลหรือตอบสนองต่อเหตุการณ์การโต้ตอบประเภทต่างๆ อย่างไร

ตอบกลับแบบเรียลไทม์

เหตุการณ์การโต้ตอบช่วยให้แอป Chat ตอบสนองได้แบบเรียลไทม์หรือพร้อมกัน การตอบกลับแบบซิงโครนัสไม่จำเป็นต้องมีการตรวจสอบสิทธิ์

หากต้องการตอบกลับแบบเรียลไทม์ แอป Chat ต้องแสดงออบเจ็กต์ Message หากต้องการตอบกลับด้วยข้อความในพื้นที่ทำงาน ออบเจ็กต์ Message จะมีออบเจ็กต์ text, cardsV2 และ accessoryWidgets ได้ หากต้องการใช้กับคำตอบประเภทอื่นๆ โปรดดูคำแนะนำต่อไปนี้

• เปิดกล่องโต้ตอบแบบอินเทอร์แอกทีฟ
• ลิงก์แสดงตัวอย่าง
• ประมวลผลข้อมูลที่ผู้ใช้ส่ง

หมายเหตุ: สำหรับเหตุการณ์การโต้ตอบ REMOVED_FROM_SPACE แอป Chat ไม่สามารถตอบกลับด้วยออบเจ็กต์ Message เนื่องจากไม่ได้อยู่ในพื้นที่อีกต่อไป

ตอบกลับด้วยข้อความ

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

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

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar
      from Google Chat. Take a look at your schedule today by typing
      `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
      learn what else I can do, type `/help`.'
    });
  }
};

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
function onAddToSpace(event) {

  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar
    from Google Chat. Take a look at your schedule today by typing
    `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
    what else I can do, type `/help`.'
  }
}

โค้ดตัวอย่างจะแสดงข้อความต่อไปนี้

ตอบกลับแบบอะซิงโครนัส

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

หากต้องการสร้างข้อความโดยใช้ Chat API โปรดดูสร้างข้อความ ดูคำแนะนำเกี่ยวกับการใช้เมธอด Chat API อื่นๆ ได้ที่ภาพรวมของ Chat API

หัวข้อที่เกี่ยวข้อง

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