POST/api/public/widget/message
Gửi tin nhắn của khách truy cập đến chatbot và trả về câu trả lời của nó – endpoint trung tâm của chat widget.
Gửi `widget_code`, `message`, `visitor_id`, và – từ tin nhắn thứ hai trở đi – `session_id` từ phản hồi trước đó. Ở lần gọi đầu tiên của một cuộc hội thoại mới, hãy để `session_id` trống hoặc đặt là `null`. Phản hồi chứa, trong đối tượng `data`, `session_id`, nội dung trả lời `response`, và tùy trường hợp, các nút (`buttons`), gợi ý sản phẩm (`products`) và trạng thái hội thoại (`state`). Cần có header `X-Widget-Token` kèm embed token và `widget_code`. Nếu thiếu token, server trả lời bằng 401 `WIDGET_TOKEN_MISSING`; nếu không hợp lệ, bằng 401 `WIDGET_TOKEN_INVALID`; các lệnh gọi từ miền chưa được phê duyệt nhận 403 `WIDGET_ORIGIN_DENIED`, widget đã bị vô hiệu hóa nhận 404 `WIDGET_DISABLED`. Nếu thiếu `visitor_id`, server trả lời bằng 400 `VISITOR_ID_REQUIRED`. Lệnh gọi này không có tính idempotent: mỗi lần gửi tạo ra một tin nhắn khách truy cập khác và một câu trả lời khác. Hãy khóa đầu vào trong khi một yêu cầu đang chờ xử lý, và không tự động thử lại.
Tổng quan
Lệnh gọi: POST /api/public/widget/message. Endpoint này thuộc nhóm “Widget chat” trong API của Zentor App. Endpoint này yêu cầu một widget embed token hợp lệ. Lệnh gọi không có tính idempotent: mỗi lệnh gọi thành công đều kích hoạt lại hành động. Tham số bắt buộc: widget_code (body), message (body), visitor_id (body). Tham số tùy chọn: session_id (body). Các trường hợp lỗi được tài liệu hóa: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. Phản hồi mẫu bên dưới cho thấy cấu trúc của một phản hồi thành công ở định dạng JSON.
Xác thực & bảo mật
Widget-Embed-Token (Header X-Widget-Token) + danh sách Origin được cho phép
Lũy đẳng (idempotent): Không
Tham số
widget_code(body, string, bắt buộc)— Mã widget từ mã nhúng của bạnmessage(body, string, bắt buộc)— Nội dung tin nhắn của khách truy cậpvisitor_id(body, string, bắt buộc)— Visitor ID do widget tạo ra và lưu trong trình duyệtsession_id(body, string)— Session ID từ phản hồi trước đó; trống hoặc `null` khi gọi lần đầu của một cuộc hội thoại mớiRequest mẫu
{"widget_code":"...","message":"Xin chào, Zentor App có thể làm gì?","visitor_id":"<UUID hoặc ID do client tạo>"}Response mẫu
{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}Mã lỗi
401 WIDGET_TOKEN_MISSING — Thiếu header `X-Widget-Token`.401 WIDGET_TOKEN_INVALID — Embed token không khớp với mã widget.400 VISITOR_ID_REQUIRED — Trường `visitor_id` bị thiếu.Hành vi đã được xác minh
Một tin nhắn hợp lệ trả về 200 kèm câu trả lời của chatbot; token bị thiếu hoặc không hợp lệ cùng với `visitor_id` bị thiếu trả về các mã lỗi đã ghi lại.
Widget chat
GET /api/public/widget/healthKiểm tra khả dụng đơn giản của dịch vụ widget.GET /api/public/widget/config/:widget_codeTrả về cấu hình công khai của widget (tên hiển thị, lời chào, thiết kế, ngôn ngữ, tính năng giọng nói) để khởi tạo trong trình duyệt.GET /api/public/widget/historyTải lịch sử tin nhắn trước đó của một cuộc hội thoại widget, ví dụ sau khi tải lại trang.POST /api/public/widget/pollLấy các tin nhắn đến sau một thời điểm cho trước – ví dụ câu trả lời của một nhân viên đã tiếp nhận cuộc hội thoại.POST /api/public/widget/ratingLưu đánh giá của khách truy cập về một cuộc hội thoại (có ích hoặc không có ích).POST /api/public/widget/trackGhi lại một sự kiện sử dụng widget ẩn danh (ví dụ: “widget đã mở”) cho các phân tích trong bảng điều khiển.POST /api/public/widget/voice-transcribeChuyển đổi bản ghi âm giọng nói của khách truy cập thành văn bản (nhập liệu bằng giọng nói), nếu tính năng giọng nói được bật cho widget.POST /api/public/widget/voice-speakChuyển đổi văn bản thành giọng nói (phát âm thanh trong widget), nếu tính năng giọng nói được bật.