GET/api/public/widget/history
Tả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.
Truyền `widget_code`, `session_id` và `visitor_id` dưới dạng tham số truy vấn. Phản hồi chứa, trong đối tượng `data`, danh sách `messages` với `role` (`user` hoặc `assistant`), `text` và `created_at` theo thứ tự hội thoại. Lệnh gọi này chỉ đọc và có tính idempotent. 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 `session_id` hoặc `visitor_id`, server trả lời bằng 400 `PARAMS_REQUIRED`. Nếu phiên không còn được nhận biết, hãy bắt đầu một cuộc hội thoại mới.
Tổng quan
Lệnh gọi: GET /api/public/widget/history. 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 có tính idempotent: các lệnh gọi lặp lại với cùng dữ liệu đầu vào trả về cùng một kết quả. Tham số bắt buộc: widget_code (query), session_id (query), visitor_id (query). Các trường hợp lỗi được tài liệu hóa: 400 PARAMS_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): Có
Tham số
widget_code(query, string, bắt buộc)— Mã widget từ mã nhúng của bạnsession_id(query, string, bắt buộc)— Session ID của cuộc hội thoại từ phản hồi của `message`visitor_id(query, string, bắt buộc)— Visitor ID do widget tạo ra và lưu trong trình duyệtResponse mẫu
{"ok":true,"data":{"messages":[{"role":"user","text":"Xin chào...","created_at":"..."},{"role":"assistant","text":"...","created_at":"..."}]}}Mã lỗi
400 PARAMS_REQUIRED — `session_id` hoặc `visitor_id` bị thiếu.Hành vi đã được xác minh
Một phiên hiện có trả về 200 kèm lịch sử tin nhắn; tham số bị thiếu trả về 400 `PARAMS_REQUIRED`.
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.POST /api/public/widget/messageGử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.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.