Skip to main content
Trang này gom các bảng tra cứu dùng chung cho Kênh Live Chat, SDK di động và Tích hợp API.

​
Bảng mã lỗi

Mọi lỗi trên Visitor API và API đọc lịch sử đều trả về cùng một cấu trúc. code là một chuỗi, không phải số; hãy rẽ nhánh theo nó, đừng rẽ nhánh theo message. Mã trạng thái HTTP nằm ở dòng trạng thái và không lặp lại trong phần thân. Với lỗi 5xx, message luôn là một câu cố định; nguyên nhân thật được ghi vào log của nền tảng. Với lỗi 4xx, message được soạn cho bạn đọc và đáng hiển thị.

​
Kênh API - Webhook nhận tin nhắn

​
Live Chat - Visitor API

Nhiều mã 404 cố ý gộp chung nhiều nguyên nhân. Ví dụ CONNECTION_NOT_FOUND dùng chung cho bốn trường hợp, và ARTIFACT_NOT_FOUND dùng chung cho tệp không tồn tại lẫn tệp không thuộc quyền. Đây là chủ ý, để không ai dò được tài nguyên nào đang tồn tại.

​
Console - Cấu hình kênh

​
Bảng giới hạn hệ thống

​
Kênh API - Chiều gửi lên

​
Kênh API - Chiều callback

​
Live Chat

​
Hạn mức chung của tổ chức

​
Danh mục kiểm tra trước khi lên Production

​
Kênh Live Chat

  • Đã lưu cấu hình kênh ít nhất một lần và đã có đoạn mã nhúng.
  • Đoạn mã đặt trước thẻ đóng </body>, data-connection-key đúng, data-app-origin giữ nguyên phần đường dẫn /chat-widget/.
  • Đã thử trên điện thoại, không chỉ trên máy tính.
  • Nếu dùng ứng dụng di động: đã truyền locale của thiết bị, vì SDK không đọc ngôn ngữ mặc định trên Console.
  • Nếu tự dựng giao diện: đã thêm tên miền của bạn vào danh sách cho phép, và không gọi với credentials: "include".

​
Kênh API

  • Đã gửi tin nhắn tới đúng host webhook lấy từ Console (https://console-agents.fpt.ai/webhooks/api), không phải host ứng dụng.
  • Khóa bí mật đã lưu vào kho bí mật, không nằm trong mã nguồn hay tệp cấu hình đưa lên Git.
  • Máy chủ đã đồng bộ giờ bằng NTP. Lệch quá 5 phút là mọi gói tin bị từ chối.
  • Hàm ký dùng chuỗi byte nguyên bản của phần thân, không phải bản đã tuần tự hóa lại.
  • So sánh chữ ký bằng hàm thời gian hằng số.
  • messageId là mã ổn định của bạn và giữ nguyên qua các lần gửi lại.
  • Webhook trả 200 ngay rồi mới xử lý bất đồng bộ. Mỗi lần gọi chỉ có 10 giây.
  • Webhook đã xử lý nhánh type == "verification" và lặp lại challenge.
  • Đã bấm Kiểm tra callback trên Console và nhận kết quả đạt.
  • Đã chống trùng theo eventId.
  • Đã lưu conversationId từ mọi callback, kể cả callback nhận thành công.
  • Đã có vòng lặp đồng bộ qua API đọc lịch sử để bù cho callback thất bại.
  • Đã tạo khóa API riêng cho việc đọc lịch sử và cất an toàn.
  • Đã xử lý mã 429 bằng cách đọc header Retry-After.
  • Đã xử lý mã 503 bằng cách gửi lại với thời gian chờ tăng dần, và không coi nó là tin nhắn bị từ chối.