Client message ID là gì? Gửi lại API chat mà không bị trùng

Client message ID (clientMessageId) là mã nhận dạng do chính bạn tạo và gửi kèm mỗi tin nhắn khi gọi API chat công khai, để việc gửi lại yêu cầu không làm tin nhắn bị xử lý hai lần. API này dùng khóa API của không gian làm việc để gửi tin nhắn của khách và nhận câu trả lời của trợ lý.

Vì sao cần client message ID?

Mạng có thể đứt đúng lúc bạn chưa nhận được phản hồi, và bạn không biết yêu cầu đã tới nơi chưa nên gửi lại. Không có mã nhận dạng, lần gửi lại có thể tạo thêm một tin nhắn và một câu trả lời nữa. Có mã, hệ thống nhận ra đó là lần gửi lại của cùng một tin nhắn.

Client message ID hoạt động như thế nào?

• Bắt buộc: thiếu mã thì API trả lỗi 400 validation_failed.
• Duy nhất theo từng khóa API, không theo cuộc trò chuyện.
• Yêu cầu trước đã xong: gửi lại cùng mã trả về đúng kết quả đã lưu với mã 200, không thêm tin nhắn mới và không gọi lại trợ lý.
• Yêu cầu trước còn đang xử lý: API trả 409 operation_in_progress, hãy chờ rồi gửi lại.
• Yêu cầu trước đã thất bại: gửi lại cùng mã được xử lý như một lần thử mới.
• Nội dung không được so sánh: cùng mã mà khác nội dung vẫn nhận kết quả cũ, nên hãy tạo mã mới cho mỗi tin nhắn mới.

Ví dụ một yêu cầu và phản hồi

Hãy gọi từ máy chủ của bạn, không đặt khóa API trong mã trình duyệt hay ứng dụng di động. $API là địa chỉ API ghi trong mã mẫu của trang Khóa API.

curl -X POST $API/api/v1/public/chat \
  -H "Authorization: Bearer sk_live_KHOA_API" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Shop có ship Đà Nẵng không?",
    "clientMessageId": "chat-7f3a91c2"
  }'

Phản hồi (rút gọn):

{
  "conversationId": "...",
  "answer": "Dạ shop có giao đi Đà Nẵng ạ...",
  "sources": [ ... ],
  "isFallback": false
}

Gửi lại đúng lệnh trên với cùng clientMessageId sẽ nhận lại đúng phản hồi này, không có tin nhắn thứ hai.

Nếu giữ giao diện chat riêng và chỉ gọi API, xem so sánh tự xây chatbot với dùng AI Chatbot, trang tích hợp và trang bảo mật.