Widget trò chuyện

Nhóm này tập hợp tất cả các endpoint công cộng mà widget trò chuyện nhúng sử dụng trên các trang web của khách hàng: kiểm tra khả năng tiếp cận (`GET /api/public/widget/health`), lấy cấu hình widget công cộng (`GET /api/public/widget/config/:widget_code`) cũng như gửi và xem lịch sử tin nhắn (`POST /api/public/widget/message`, `GET /api/public/widget/history`). Việc cấp quyền miền được quản lý bởi Zentor trong quá trình tạo widget; không có giao diện cấu hình nào trong bảng điều khiển Tenant cho mục đích này. Nếu miền nguồn chưa được cấp quyền, mã lỗi `WIDGET_ORIGIN_DENIED` có thể xuất hiện. Việc tạo widget chỉ dành cho Master-Admin, trong khi Tenant sẽ nhận được mã nhúng hoàn chỉnh.

Hệ thống khóa phát triển API chung không tồn tại. `health` và `config` có thể truy cập mà không cần xác thực vì chúng được dùng để khởi tạo widget trong trình duyệt. Ngược lại, `message` và `history` yêu cầu tiêu đề `X-Widget-Token` và sẽ được kiểm tra thêm danh sách cho phép nguồn (Origin-Allowlist) phía máy chủ. Token nhúng sẽ được hiển thị một lần dưới dạng văn bản rõ ràng khi tạo widget và không được phép xuất hiện trong các kho lưu trữ công cộng, ảnh chụp màn hình hỗ trợ hoặc nhật ký trình duyệt.

Mỗi trang chi tiết của nhóm này mô tả riêng lẻ phương thức, đường dẫn, xác thực, tính idempotent và các mã lỗi được tài liệu hóa của từng endpoint. Một cuộc gọi thành công đến một endpoint không tự động đảm bảo rằng các endpoint khác trong cùng nhóm cũng thành công — đặc biệt là việc kiểm tra `health` màu xanh không xác nhận widget hợp lệ, miền nguồn được cấp quyền hay khả năng tiếp cận của nhà cung cấp AI.

Giới hạn toàn nền tảng API được xác nhận là 2.000 yêu cầu trong vòng 15 phút. Giới hạn riêng biệt cho một endpoint widget cụ thể chỉ được đề cập nếu được chứng minh rõ ràng cho endpoint đó. `message` không có tính idempotent; client không được tự động lặp lại quá trình gửi bị gián đoạn không rõ ràng mà không kiểm tra trước xem tin nhắn đầu tiên đã được xử lý chưa.

Kiểm tra kỹ thuật nhóm này dựa trên Registry tại `app/frontend/src/content/api-reference/groups/widget.ts` và các route backend tương ứng. Mỗi trang chi tiết sẽ chỉ rõ liệu đường dẫn thành công đã được kiểm tra trực tiếp, đường dẫn tiêu cực đã được kiểm tra hay chỉ là tương đồng mã nguồn — sự phân biệt này áp dụng cho toàn bộ nhóm và không thể thay thế bằng các tuyên bố thành công chung chung.