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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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