POST/api/public/widget/message
ส่งข้อความของผู้เยี่ยมชมไปยังแชทบอทและส่งคำตอบกลับมา – เอนด์พอยต์หลักของแชทวิดเจ็ต
ส่ง `widget_code`, `message`, `visitor_id`, และตั้งแต่ข้อความที่สองเป็นต้นไปให้ส่ง `session_id` จากการตอบกลับครั้งก่อน เมื่อเรียกครั้งแรกของการสนทนาใหม่ ให้เว้น `session_id` ว่างไว้หรือตั้งเป็น `null` การตอบกลับจะมี `session_id` ข้อความตอบกลับ `response` และตามความเหมาะสมอาจมีปุ่ม (`buttons`) ข้อเสนอสินค้า (`products`) และสถานะการสนทนา (`state`) ในออบเจ็กต์ `data` จำเป็นต้องมีส่วนหัว `X-Widget-Token` พร้อม Embed Token และ `widget_code` หากโทเค็นหายไป เซิร์ฟเวอร์จะตอบกลับด้วย 401 `WIDGET_TOKEN_MISSING` หากไม่ถูกต้องคือ 401 `WIDGET_TOKEN_INVALID` การเรียกจากโดเมนที่ไม่ได้รับอนุมัติจะได้รับ 403 `WIDGET_ORIGIN_DENIED` วิดเจ็ตที่ถูกปิดใช้งานจะได้รับ 404 `WIDGET_DISABLED` หาก `visitor_id` หายไป เซิร์ฟเวอร์จะตอบกลับด้วย 400 `VISITOR_ID_REQUIRED` การเรียกนี้ไม่ใช่ idempotent: การส่งแต่ละครั้งจะสร้างข้อความของผู้เยี่ยมชมและคำตอบใหม่อีกครั้ง ล็อกการป้อนข้อมูลในขณะที่คำขอกำลังดำเนินการ และห้ามลองใหม่โดยอัตโนมัติ
ภาพรวม
การเรียกใช้: POST /api/public/widget/message เอนด์พอยต์นี้อยู่ในกลุ่ม “แชทวิดเจ็ต” ของ API ของ Zentor App เอนด์พอยต์นี้ต้องใช้โทเค็นฝังวิดเจ็ต (widget embed token) ที่ถูกต้อง การเรียกใช้นี้ไม่เป็นแบบ idempotent: การเรียกที่สำเร็จแต่ละครั้งจะทริกเกอร์การดำเนินการใหม่อีกครั้ง พารามิเตอร์ที่จำเป็น: widget_code (body), message (body), visitor_id (body) พารามิเตอร์ที่ไม่บังคับ: session_id (body) กรณีข้อผิดพลาดที่จัดทำเอกสารไว้: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED ตัวอย่างการตอบกลับด้านล่างแสดงโครงสร้างของการตอบกลับที่สำเร็จในรูปแบบ JSON
การยืนยันตัวตนและความปลอดภัย
Widget-Embed-Token (Header X-Widget-Token) + รายการ Origin ที่อนุญาต
Idempotent (เรียกซ้ำได้ผลเหมือนเดิม): ไม่
พารามิเตอร์
widget_code(body, string, จำเป็น)— โค้ดวิดเจ็ตจากโค้ดฝังของคุณmessage(body, string, จำเป็น)— ข้อความของผู้เยี่ยมชมvisitor_id(body, string, จำเป็น)— Visitor ID ที่สร้างโดยวิดเจ็ตและจัดเก็บไว้ในเบราว์เซอร์session_id(body, string)— Session ID จากการตอบกลับครั้งก่อน เว้นว่างหรือ `null` ในการเรียกครั้งแรกของการสนทนาใหม่ตัวอย่างคำขอ
{"widget_code":"...","message":"สวัสดี Zentor App ทำอะไรได้บ้าง?","visitor_id":"<UUID หรือ ID ที่สร้างโดยไคลเอนต์>"}ตัวอย่างการตอบกลับ
{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}รหัสข้อผิดพลาด
401 WIDGET_TOKEN_MISSING — ส่วนหัว `X-Widget-Token` หายไป401 WIDGET_TOKEN_INVALID — Embed Token ไม่ตรงกับโค้ดวิดเจ็ต400 VISITOR_ID_REQUIRED — ช่อง `visitor_id` หายไปพฤติกรรมที่ตรวจสอบแล้ว
ข้อความที่ถูกต้องจะได้รับ 200 พร้อมคำตอบของแชทบอท โทเค็นที่หายไปหรือไม่ถูกต้อง รวมถึง `visitor_id` ที่หายไป จะได้รับโค้ดข้อผิดพลาดที่มีการบันทึกไว้
แชทวิดเจ็ต
GET /api/public/widget/healthตรวจสอบความพร้อมใช้งานของบริการวิดเจ็ตแบบง่าย ๆGET /api/public/widget/config/:widget_codeส่งคืนการตั้งค่าสาธารณะของวิดเจ็ต (ชื่อที่แสดง ข้อความต้อนรับ ดีไซน์ ภาษา ฟังก์ชันเสียง) สำหรับการเริ่มต้นในเบราว์เซอร์GET /api/public/widget/historyโหลดประวัติข้อความก่อนหน้าของการสนทนาในวิดเจ็ต เช่น หลังจากโหลดหน้าใหม่POST /api/public/widget/pollดึงข้อความที่มาถึงหลังจากเวลาที่ระบุ – เช่น คำตอบของพนักงานที่รับช่วงการสนทนาPOST /api/public/widget/ratingจัดเก็บคะแนนของผู้เยี่ยมชมสำหรับบทสนทนา (มีประโยชน์หรือไม่มีประโยชน์)POST /api/public/widget/trackบันทึกเหตุการณ์การใช้งานแบบไม่ระบุตัวตนของวิดเจ็ต (เช่น “วิดเจ็ตถูกเปิด”) สำหรับการวิเคราะห์ในแดชบอร์ดPOST /api/public/widget/voice-transcribeแปลงการบันทึกเสียงของผู้เยี่ยมชมเป็นข้อความ (การป้อนด้วยเสียง) หากเปิดใช้งานฟังก์ชันเสียงสำหรับวิดเจ็ตPOST /api/public/widget/voice-speakแปลงข้อความเป็นเสียงพูด (การส่งออกด้วยเสียงในวิดเจ็ต) หากเปิดใช้งานฟังก์ชันเสียงแล้ว