สร้างอินเทอร์เฟซ Google Chat

หน้านี้แสดงภาพรวมของวิธีสร้างอินเทอร์เฟซผู้ใช้ (UI) สําหรับส่วนเสริมของ Google Workspace ที่ขยาย Google Chat

ใน Google Chat ส่วนเสริมจะปรากฏต่อผู้ใช้เป็นแอป Google Chat ดูข้อมูลเพิ่มเติมได้ที่ภาพรวมการขยาย Google Chat

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

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

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

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

ทริกเกอร์

ส่วนนี้จะอธิบายทริกเกอร์ที่ส่วนเสริมของ Google Workspace ใช้ใน Chat

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

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

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

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

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

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

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

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

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

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

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

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

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

หากต้องการตอบสนองต่อทริกเกอร์ โปรดดูคู่มือต่อไปนี้

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

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

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

แชท

แชท
chat.user object (User)
ผู้ใช้ Chat ที่โต้ตอบกับแอป Chat
chat.space object (Space)
พื้นที่ใน Chat ที่ผู้ใช้โต้ตอบกับแอป Chat
chat.eventTime

string (Timestamp format)

เวลาที่มีการโต้ตอบ

ฟิลด์สหภาพ payload

payload ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
chat.messagePayload

object (MessagePayload)

เพย์โหลดที่แอป Chat ได้รับจากทริกเกอร์ข้อความ
chat.addedToSpacePayload

object (AddedToSpacePayload)

เพย์โหลดที่แอป Chat ได้รับจากทริกเกอร์เพิ่มลงในพื้นที่ทำงาน
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

เพย์โหลดที่แอป Chat ได้รับจากทริกเกอร์นำออกจากพื้นที่ทำงาน
chat.buttonClickedPayload

object (ButtonClickedPayload)

เพย์โหลดที่แอป Chat ได้รับเมื่อผู้ใช้คลิกปุ่มจากข้อความหรือการ์ด หากผู้ใช้คลิกปุ่มเพื่อส่งข้อมูล ออบเจ็กต์ commonEventObject.formInputs จะมีค่าที่รวบรวมจากผู้ใช้ โปรดดูรายละเอียดที่หัวข้อ รวบรวมข้อมูลจากผู้ใช้ Google Chat
chat.widgetUpdatedPayload

object (WidgetUpdatedPayload)

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

ออบเจ็กต์ CommonEventObject.parameters['autocomplete_widget_query'] มีค่าสตริงที่ผู้ใช้พิมพ์ลงในเมนู

chat.appCommandPayload

object (AppCommandPayload)

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

เพย์โหลด

เหตุการณ์จะมีเพย์โหลดที่มีทรัพยากร Chat API อย่างน้อย 1 รายการ ทั้งนี้ขึ้นอยู่กับประเภทของการโต้ตอบ

เพย์โหลดข้อความ
MessagePayload
chat.messagePayload.message object (Message)
ข้อความใน Chat ที่ทริกเกอร์เหตุการณ์
chat.messagePayload.space object (Space)
พื้นที่ใน Chat ที่ผู้ใช้ส่งข้อความซึ่งเรียกใช้แอป Chat

เพิ่มลงในน้ำหนักบรรทุกของพื้นที่ทำงาน
AddedToSpacePayload
chat.addedToSpacePayload.space object (Space)
พื้นที่ทำงานใน Chat ที่ผู้ใช้เพิ่มหรือติดตั้งแอป Chat

เมื่อผู้ดูแลระบบติดตั้งแอปใน Chat ระบบจะตั้งค่าช่อง space.adminInstalled เป็น true

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

นำออกจากน้ำหนักบรรทุกของพื้นที่ทำงาน
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
พื้นที่ใน Chat ที่ผู้ใช้นำหรือถอนการติดตั้งแอป Chat ออก

เมื่อผู้ดูแลระบบถอนการติดตั้งแอป Chat ระบบจะตั้งค่าช่อง space.adminInstalled เป็น false

เพย์โหลดการคลิกปุ่ม
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
ข้อความใน Chat ที่มีปุ่มที่ผู้ใช้คลิก
chat.buttonClickedPayload.space object (Space)
พื้นที่ใน Chat ที่ผู้ใช้คลิกปุ่มจากข้อความในแอป Chat
chat.buttonClickedPayload.isDialogEvent boolean
ระบุว่าผู้ใช้คลิกปุ่มเพื่อโต้ตอบกับกล่องโต้ตอบหรือไม่
chat.buttonClickedPayload.dialogEventType enum (DialogEventType)
หาก isDialogEvent เป็น true ประเภทการโต้ตอบในกล่องโต้ตอบ

Enum DialogEventType

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

เพย์โหลดที่อัปเดตวิดเจ็ต
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
พื้นที่ใน Chat ที่มีการโต้ตอบ

เพย์โหลดคําสั่งแอป
AppCommandPayload
chat.appCommandPayload.appCommandMetadata object (AppCommandMetadata)
ข้อมูลเมตาเกี่ยวกับคําสั่งที่ผู้ใช้ใช้ และวิธีเรียกใช้คําสั่ง
chat.appCommandPayload.space object (Space)
พื้นที่ใน Chat ที่ผู้ใช้ใช้คำสั่ง
chat.appCommandPayload.thread object (Thread)
หากการโต้ตอบเกิดขึ้นในชุดข้อความ ให้ระบุชุดข้อความแชทที่ผู้ใช้ใช้คําสั่ง
chat.appCommandPayload.message object (Message)
ข้อความที่ผู้ใช้ส่งด้วยคำสั่งเครื่องหมายทับ
chat.appCommandPayload.configCompleteRedirectUri string
URL ที่จะเปลี่ยนเส้นทางผู้ใช้ไปหลังจากที่ดำเนินการเสร็จสิ้นนอก Google Chat หากจำเป็นต้องมีการให้สิทธิ์หรือการกำหนดค่าสำหรับคำสั่ง
chat.appCommandPayload.isDialogEvent boolean
ระบุว่าคำสั่งจะเปิดกล่องโต้ตอบหรือไม่
chat.appCommandPayload.dialogEventType enum (DialogEventType)
ประเภทการโต้ตอบกับกล่องโต้ตอบ

Enum DialogEventType

ค่าของ dialogEventType ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
TYPE_UNSPECIFIED ค่าเริ่มต้น ไม่ระบุ
REQUEST_DIALOG ผู้ใช้ส่งคําขอกล่องโต้ตอบ เช่น ใช้คำสั่งเครื่องหมายทับ หรือคลิกปุ่มจากข้อความ
SUBMIT_DIALOG ผู้ใช้คลิกองค์ประกอบแบบอินเทอร์แอกทีฟภายในกล่องโต้ตอบ เช่น ผู้ใช้กรอกข้อมูลในกล่องโต้ตอบและคลิกปุ่มเพื่อส่งข้อมูล
ข้อมูลเมตาของคําสั่งแอป
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string (int64 format)

รหัสคําสั่ง
chat.appCommandPayload.appCommandMetadata.appCommandType enum (AppCommandType)
ประเภทคําสั่ง

Enum AppCommandType

ค่าของ AppCommandType ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
APP_COMMAND_TYPE_UNSPECIFIED ค่าเริ่มต้น ไม่ระบุ
SLASH_COMMAND ผู้ใช้ใช้คำสั่งนี้โดยการส่งข้อความที่ขึ้นต้นด้วยเครื่องหมายทับ /

การดำเนินการในแชท

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

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

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

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

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

ตอบกลับโดยใช้ Google Chat API

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

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

ดูข้อมูลเกี่ยวกับการตรวจสอบสิทธิ์และการเรียกใช้ Chat API ได้ที่หัวข้อภาพรวมของ Chat API