รับและตอบกลับการโต้ตอบของผู้ใช้

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

หากต้องการสร้างอินเทอร์เฟซแบบอินเทอร์แอกทีฟสำหรับแอปใน Chat ให้ใช้คอมโพเนนต์ต่อไปนี้

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

แอปใน Chat สามารถสร้างและแสดงอินเทอร์เฟซได้ด้วยวิธีต่อไปนี้

  • ข้อความที่อาจมีข้อความ การ์ดแบบคงที่หรือแบบอินเทอร์แอกทีฟ และปุ่มเสริม
  • หน้าแรก (หน้าแรกของแอป) ที่ปรากฏในแท็บหน้าแรกของข้อความส่วนตัวแบบ 1:1 กับแอปใน Chat
  • กล่องโต้ตอบ ซึ่งเป็นการ์ดที่เปิดในหน้าต่างใหม่และมักจะแจ้งให้ผู้ใช้ส่งข้อมูล
  • ตัวอย่างลิงก์ ซึ่งเป็นการ์ดที่แสดงตัวอย่างข้อมูลเกี่ยวกับบริการภายนอก

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

วิธีการทำงานของการโต้ตอบของผู้ใช้

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

แผนภาพต่อไปนี้แสดงวิธีที่แอป Google Chat ประมวลผลและตอบสนองต่อการโต้ตอบของผู้ใช้

สถาปัตยกรรมของวิธีที่แอป Google Chat ประมวลผลการโต้ตอบของผู้ใช้

ทริกเกอร์

ทริกเกอร์คือวิธีที่เฉพาะเจาะจงที่ผู้ใช้เรียกใช้แอปใน Chat โดยใช้ UI ของ Chat เช่น การใช้ @พูดถึงหรือคำสั่งแอป

ตารางต่อไปนี้แสดงทริกเกอร์ของ Chat, คำอธิบาย และวิธีที่แอปใน Chat มักจะตอบสนอง

ทริกเกอร์ คำอธิบาย คำตอบทั่วไป
เพิ่มไปยังพื้นที่ทำงานแล้ว

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

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

ผู้ใช้โต้ตอบกับแอปใน Chat ในข้อความด้วยวิธีใดวิธีหนึ่งต่อไปนี้

  • ส่งข้อความในพื้นที่ทำงานของข้อความส่วนตัว (DM) ด้วยแอป Chat
  • @พูดถึงแอปใน Chat ในพื้นที่ทำงานประเภทใดก็ได้
  • ส่งข้อความที่มีลิงก์ที่ตรงกับรูปแบบ URL สำหรับตัวอย่างลิงก์
  • พิมพ์ข้อความลงในเมนูแบบเลือกหลายรายการของวิดเจ็ต selectionInput
 แอปใน Chat จะตอบกลับตามเนื้อหาของข้อความ เช่น แอปใน Chat จะตอบกลับด้วยข้อความ แนบการ์ดแสดงตัวอย่างลิงก์ หรือแนะนำรายการในเมนูแบบเลือกได้หลายรายการ
นำออกจากพื้นที่ทำงานแล้ว

ผู้ใช้นำแอปใน Chat ออกจากพื้นที่ทำงาน หรือผู้ดูแลระบบ Google Workspace ถอนการติดตั้งแอปใน Chat สำหรับผู้ใช้ในองค์กร

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

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

ผู้ใช้เรียกใช้คำสั่งแอปใน Chat (เช่น คำสั่งเครื่องหมายทับ คำสั่งด่วน หรือการดำเนินการกับข้อความ)

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

ผู้ใช้เปิดแท็บหน้าแรกในพื้นที่ทำงานของข้อความส่วนตัว (DM) แบบ 1:1 ด้วยแอปใน Chat หรือโต้ตอบกับวิดเจ็ตในการ์ดหน้าแรก

 แอปใน Chat จะแสดงผลออบเจ็กต์ RenderActions ที่พุชการ์ดหน้าแรก (pushCard) หรืออัปเดตการ์ดหน้าแรกที่แสดง (updateCard)

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

กำหนดค่าพรอมต์เริ่มต้น

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

วิธีเพิ่มและกำหนดค่าพรอมต์เริ่มต้น

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

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

  2. ในส่วนฟีเจอร์แบบอินเทอร์แอกทีฟ ให้ค้นหาพรอมต์เริ่มต้น แล้วคลิกเพิ่มพรอมต์

  3. ในช่องอันดับ (1-3) ให้ป้อนตัวเลขตั้งแต่ 1 ถึง 3 เพื่อระบุลำดับการแสดงผล

  4. ในส่วนการเลือกประเภท ให้เลือกวิธีที่พรอมต์จะทำงาน ดังนี้

    • พรอมต์ข้อความ: เติมข้อความที่กำหนดไว้ล่วงหน้าลงในช่องสำหรับเขียนเมื่อผู้ใช้คลิกชิปพรอมต์
    • Command Prompt: เรียกใช้คำสั่งเครื่องหมายทับหรือคำสั่งด่วนที่ลงทะเบียนไว้เมื่อคลิก คุณเลือกคำสั่งที่ต้องใช้อาร์กิวเมนต์เพิ่มเติมไม่ได้

  5. กำหนดค่าพรอมต์ตามประเภทที่เลือก ดังนี้

    • หากเลือกพรอมต์ข้อความ ให้ทำดังนี้

      1. ในส่วนชื่อ ให้ป้อนชื่อพรอมต์ที่แสดงบนชิป (สูงสุด 30 อักขระ)
      2. ในข้อความพรอมต์ ให้ป้อนข้อความที่สร้างขึ้นในช่องสำหรับเขียน (ไม่เกิน 60 อักขระ)
      3. ไม่บังคับ: เพิ่มชื่อและข้อความที่แปลแล้วสำหรับผู้ใช้ในภาษาอื่นๆ โดยทำดังนี้
      4. ในส่วนพรอมต์ที่แปลแล้ว ให้คลิกเพิ่มภาษา
      5. ในส่วนภาษา ให้เลือกภาษาที่รองรับจากเมนูแบบเลื่อนลง
      6. ในชื่อที่แปลแล้ว ให้ป้อนชื่อที่แปลแล้ว (สูงสุด 30 อักขระ)
      7. ในข้อความพรอมต์ที่แปลแล้ว ให้ป้อนข้อความพรอมต์ที่แปลแล้ว (ไม่เกิน 60 อักขระ)
      8. ทำซ้ำเพื่อเพิ่มภาษาอื่นๆ ตามต้องการ

    • หากเลือก Command Prompt ให้ทำดังนี้

      1. ในคำสั่งเครื่องหมายทับ / คำสั่งด่วน ให้เลือกคำสั่งจากเมนูแบบเลื่อนลง

  6. คลิกเสร็จสิ้น แล้วคลิกบันทึกที่ด้านล่างของหน้า

จัดการการลองเรียกใช้ HTTP ซ้ำไปยังบริการของคุณ

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

ออบเจ็กต์เหตุการณ์

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

ในปี 2025 แอป Google Chat ได้รับการขยายให้รองรับเหตุการณ์ส่วนเสริม และนี่เป็นค่าเริ่มต้นสำหรับแอป Chat ใหม่ตั้งแต่เดือนกรกฎาคม 2025 ในเอกสารประกอบของ Chat เหตุการณ์ส่วนเสริมคือประเภทเหตุการณ์มาตรฐานที่แสดงในคู่มือและตัวอย่างโค้ด เอกสารประกอบสำหรับเหตุการณ์ใน Chat (สำหรับแอปใน Chat ที่ไม่ใช่ส่วนเสริมของ Google Workspace) จะแยกออกเป็นส่วนที่ยุบได้ (เช่น แอปใน Chat ที่ไม่ใช่ส่วนเสริม: รับและตอบกลับเหตุการณ์การโต้ตอบ)

กำหนดประเภทเหตุการณ์และการตอบสนอง

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

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

ประเภทแอป รับเหตุการณ์ของส่วนเสริม
(ค่าเริ่มต้นสำหรับแอปใหม่ที่สร้างหลังเดือนกรกฎาคม 2025)		 รับเหตุการณ์ใน Chat
(ค่าเริ่มต้นก่อนหน้านี้ ก่อนเดือนกรกฎาคม 2025)
แอป Apps Script
ตรวจสอบไฟล์ Manifest (appsscript.json)		 ออบเจ็กต์ chat ได้รับการกำหนดค่าภายใน addOns ดังนี้ 
{
  "addOns": {
    "chat": {}
  }
}
 		ออบเจ็กต์ chat ได้รับการกำหนดค่าที่รูทของไฟล์ Manifest ดังนี้ 
{
  "chat": {}
}
แอปอื่นๆ
ตรวจสอบหน้าการกำหนดค่า Google Chat API		 เลือกช่องทำเครื่องหมาย "สร้างแอป Chat นี้เป็นส่วนเสริมของ Google Workspace" แล้ว ไม่ได้เลือกช่องทำเครื่องหมาย "สร้างแอป Chat นี้เป็นส่วนเสริมของ Google Workspace"
แหล่งข้อมูล ในคู่มือและตัวอย่างโค้ด

เอกสารอ้างอิงเหตุการณ์: ออบเจ็กต์เหตุการณ์ของส่วนเสริม		 ส่วนที่ยุบ (เช่น แอป Chat ที่ไม่ใช่ส่วนเสริม: รับและตอบกลับเหตุการณ์การโต้ตอบ)

เอกสารอ้างอิงเหตุการณ์: เหตุการณ์การโต้ตอบของ Chat API
วิธีตอบสนอง แสดงผลการดำเนินการ เช่น DataActions หรือ RenderActions
ดูวิธีตอบกลับด้วยการดำเนินการ		 แสดงผลทรัพยากร Message
ดูวิธีตอบกลับด้วยข้อความ

เพย์โหลดของออบเจ็กต์เหตุการณ์

ออบเจ็กต์เหตุการณ์ของส่วนเสริมแต่ละรายการจะมี commonEventObject พร้อมรายละเอียดโฮสต์และแพลตฟอร์ม (hostApp: "CHAT", clientPlatform, userLocale, userTimezone, parameters และ formInputs) และออบเจ็กต์ chat ที่มีบริบทเฉพาะของ Chat ดังนี้

  • สำหรับทริกเกอร์หน้าแรกของแอป (เมื่อผู้ใช้เปิดแท็บหน้าแรกในข้อความส่วนตัวแบบ 1:1 กับแอป Chat) ออบเจ็กต์ chat จะมี chat.user และ chat.eventTime โดยไม่มีช่อง payload ของ Union เมื่อผู้ใช้คลิกปุ่มในการ์ดหน้าแรก ออบเจ็กต์เหตุการณ์จะมี chat.buttonClickedPayload พร้อมกับ commonEventObject.parameters (และ commonEventObject.formInputs หากการ์ดมีอินพุตแบบฟอร์ม)
  • สำหรับการโต้ตอบในพื้นที่ทำงานและข้อความ (เพิ่มไปยังพื้นที่ทำงาน, ข้อความ, นำออกจากพื้นที่ทำงาน, คำสั่งแอป หรือการโต้ตอบกับปุ่มและวิดเจ็ต) ออบเจ็กต์ chat จะมี chat.user, chat.space, chat.eventTime และเพย์โหลดการโต้ตอบที่เกี่ยวข้อง ดังนี้
    • messagePayload: มี space, message และ configCompleteRedirectUri เมื่อผู้ใช้ส่งข้อความ
    • addedToSpacePayload: มี space, interactionAdd และ configCompleteRedirectUri เมื่อเพิ่มแอปใน Chat ไปยังพื้นที่ทำงาน
    • removedFromSpacePayload: มี space เมื่อนำแอปใน Chat ออกจากพื้นที่ทำงาน
    • buttonClickedPayload: มี space, message, isDialogEvent และ dialogEventType เมื่อผู้ใช้คลิกปุ่มบนการ์ดหรือกล่องโต้ตอบ
    • widgetUpdatedPayload: มี space เมื่อผู้ใช้โต้ตอบกับวิดเจ็ต เช่น การพิมพ์ในเมนูแบบเลือกได้หลายรายการที่มีแหล่งข้อมูลภายนอก
    • appCommandPayload: มี space, message, appCommandMetadata, isDialogEvent, dialogEventType และ configCompleteRedirectUri เมื่อผู้ใช้เรียกใช้คำสั่งแอป

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

ส่งคำตอบ

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

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

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

  • DataActions: สร้างหรืออัปเดตข้อความแชท (CreateMessageAction, UpdateMessageAction) หรือแนบตัวอย่างลิงก์ (UpdateInlinePreviewAction) โดยใช้ chatDataActionMarkup
  • RenderActions: สร้าง อัปเดต หรือปิดหน้าแรกหรือกล่องโต้ตอบ (pushCard, updateCard, endNavigation: "CLOSE_DIALOG") หรือให้คำแนะนำการป้อนข้อมูลแบบไดนามิกสำหรับเมนูแบบเลือกได้หลายรายการ (modifyCard)
  • AuthorizationError: แจ้งให้ผู้ใช้ที่มีการ์ดการให้สิทธิ์พื้นฐาน (basic_authorization_prompt) ลงชื่อเข้าใช้หรือตรวจสอบสิทธิ์กับบริการภายนอก

ตารางต่อไปนี้แสดงวิธีที่แอปใน Chat สามารถตอบกลับด้วยการดำเนินการ แอปใน Chat สามารถแสดงผลออบเจ็กต์ JSON โดยตรงหรือสร้างการตอบกลับโดยใช้ AddOnResponseService และ CardService ของ Apps Script

คำตอบจากแอปใน Chat การดำเนินการที่จำเป็นในการแสดงผล (JSON) การดำเนินการที่จำเป็นเพื่อส่งคืน (Apps Script)
ส่งข้อความหรืออัปเดตข้อความ DataActions (createMessageAction หรือ updateMessageAction) DataActionsResponse
แสดงตัวอย่างลิงก์ในข้อความที่ผู้ใช้ Chat ส่งในพื้นที่ทำงาน DataActions (updateInlinePreviewAction) DataActionsResponse
แสดงผลหรืออัปเดตหน้าแรกในแท็บหน้าแรกของข้อความส่วนตัว RenderActions (pushCard หรือ updateCard) ActionResponse
เปิด อัปเดต หรือปิดกล่องโต้ตอบ RenderActions (pushCard, updateCard หรือ endNavigation: "CLOSE_DIALOG") ActionResponse
หากต้องการรวบรวมข้อมูลจากการ์ดหรือกล่องโต้ตอบ ให้แนะนำรายการที่เลือกโดยอิงตามสิ่งที่ผู้ใช้พิมพ์ลงในเมนูแบบเลือกได้หลายรายการ RenderActions (modifyCard) ActionResponse
ขอการกำหนดค่าหรือการให้สิทธิ์สำหรับบริการภายนอก AuthorizationError (basic_authorization_prompt) AuthorizationException

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

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

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

แอปใน Chat สามารถใส่สิ่งต่อไปนี้ในข้อความได้

  • ข้อความที่มีไฮเปอร์ลิงก์, @พูดถึง และอีโมจิ ดูหัวข้อจัดรูปแบบข้อความ
  • การ์ดอย่างน้อย 1 ใบ ซึ่งอาจปรากฏในข้อความหรือเปิดในหน้าต่างใหม่เป็นกล่องโต้ตอบ โปรดดูหัวข้อสร้างการ์ดสําหรับแอป Google Chat
  • วิดเจ็ตเสริมอย่างน้อย 1 รายการ ซึ่งเป็นปุ่มที่ปรากฏหลังข้อความหรือการ์ดในข้อความ

หากต้องการตอบกลับด้วยข้อความ ให้แสดงผล DataActions พร้อมออบเจ็กต์ CreateMessageAction ดังนี้

{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

แทนที่ MESSAGE ด้วยทรัพยากร Message จาก Chat API

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

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Chat.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  const chatEvent = req.body.chat;
  // Send an onboarding message when added to a Chat space
  if (chatEvent.addedToSpacePayload) {
    res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      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`.'
    }}}}});
  }
};

Python

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  chat_event = request.get_json()["chat"]
  if "addedToSpacePayload" in chat_event:
    return json.jsonify({ "hostAppDataAction": { "chatDataAction": {
      "createMessageAction": { "message": {
        "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`.'
      }}
    }}})

Java

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    JsonNode chatEvent = event.at("/chat");
    if (!chatEvent.at("/addedToSpacePayload").isEmpty()) {
      return new GenericJson() { {
        put("hostAppDataAction", new GenericJson() { {
          put("chatDataAction", new GenericJson() { {
            put("createMessageAction", new GenericJson() { {
              put("message", new Message().setText(
                "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`."
              ));
            } });
          } });
        } });
      } };
    }
    return new GenericJson();
  }
}

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {Object} Response from the Chat app.
 */
function onAddedToSpace(event) {
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    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 ยังอัปเดตข้อความที่ส่งได้ด้วย เช่น แอปใน Chat สามารถอัปเดตข้อความหลังจากที่ผู้ใช้ส่งกล่องโต้ตอบหรือคลิกปุ่มบนการ์ดในข้อความ

หากต้องการอัปเดตข้อความของแอป Chat เพื่อตอบสนองต่อการโต้ตอบ ให้แสดงผล DataActions พร้อม UpdateMessageAction ดังนี้

{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

แทนที่ MESSAGE ด้วยทรัพยากร Message จาก Chat API

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

ตอบกลับแบบอะซิงโครนัสโดยใช้ Google Chat API

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

  • ตอบสนองต่อการโต้ตอบหลังจากผ่านไป 30 วินาที (เช่น หลังจากทำงานที่ใช้เวลานานเสร็จ)
  • ส่งข้อความตามกำหนดเวลา หรือส่งการแจ้งเตือนเกี่ยวกับการเปลี่ยนแปลงไปยังแหล่งข้อมูลภายนอก
  • ทำงานนอกพื้นที่ทำงานที่มีการโต้ตอบเกิดขึ้น
  • ทำงานใน Chat ที่ไม่พร้อมใช้งานเป็นการดำเนินการแบบซิงโครนัส เช่น แสดงรายการพื้นที่ทำงานหรือเพิ่มสมาชิกไปยังพื้นที่ทำงาน
  • ทำงานในนามของผู้ใช้ Chat (ซึ่งต้องมีการตรวจสอบสิทธิ์ผู้ใช้)

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

Node.js

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

Python

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return {}

Java

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

Apps Script

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

หากต้องการส่งข้อความโดยใช้ Chat API ให้ตั้งค่าการตรวจสอบสิทธิ์และเรียกใช้เมธอด spaces.messages.create โปรดดูขั้นตอนในหัวข้อส่งข้อความ ดูคำแนะนำในการใช้เมธอด Chat API เพิ่มเติมได้ที่ภาพรวมของ Chat API

แอปใน Chat ที่ไม่ใช่ส่วนเสริม: รับและตอบสนองต่อการโต้ตอบของผู้ใช้

แอป Chat ที่ไม่ใช่ส่วนเสริมของ Google Workspace จะได้รับเหตุการณ์การโต้ตอบของ Chat API (Event) แทนออบเจ็กต์เหตุการณ์ของส่วนเสริม Google Workspace (EventObject) และตอบกลับโดยแสดงผลทรัพยากร Message แทนการดำเนินการ

หากต้องการอัปเกรดแอป Chat ที่ไม่ใช่ส่วนเสริมเป็นเฟรมเวิร์กส่วนเสริมของ Google Workspace โปรดดูหัวข้อแปลงแอป Google Chat เป็นส่วนเสริมของ Google Workspace

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

สำหรับการโต้ตอบของผู้ใช้แต่ละประเภท Google Chat จะส่งออบเจ็กต์ Event ซึ่งมีประเภทที่แสดงโดยช่อง eventType ไปยังแอปใน 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 ทำได้

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

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

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

  • ฟิลด์ isDialogEvent ตั้งค่าเป็น true
  • DialogEventType (REQUEST_DIALOG, SUBMIT_DIALOG หรือ CANCEL_DIALOG) จะชี้แจงว่าการโต้ตอบจะทริกเกอร์กล่องโต้ตอบให้เปิด ส่งข้อมูลจากกล่องโต้ตอบ หรือปิดกล่องโต้ตอบ

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

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

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

  2. ในส่วนฟีเจอร์แบบอินเทอร์แอกทีฟ ให้ล้างสร้างแอปใน Chat นี้เป็นส่วนเสริมของ Google Workspace และกำหนดค่าฟังก์ชันการทำงาน, ปลายทางการตั้งค่าการเชื่อมต่อรายการเดียว (URL ปลายทาง HTTP, Apps Script, ชื่อหัวข้อ Cloud Pub/Sub หรือ Dialogflow), คำสั่ง, พรอมต์เริ่มต้น, ตัวอย่างลิงก์ และระดับการเข้าถึง

  3. คลิกบันทึก

ตอบกลับด้วยข้อความในแอป Chat ที่ไม่ใช่ส่วนเสริม

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

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.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // 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`.'
    });
  }
};

Python

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      '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`.'
    })
  return json.jsonify({})

Java

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return new Message().setText(
          "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`.");
      default:
        return new Message();
    }
  }
}

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.
 */
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`.'
  };
}