Client message ID (clientMessageId): retry the chat API safely

A client message ID (clientMessageId) is an identifier you generate yourself and send with every message to the public chat API, so that retrying a request never processes the same message twice. The API uses your workspace's API key to send a customer's message and return the assistant's answer.

Why do you need a client message ID?

Networks fail at awkward moments, sometimes after your request left but before the response arrived. You cannot tell whether the request landed, so you send it again. Without an identifier, the retry can create a second message and a second answer. With one, the API recognises the retry as the same message.

How does a client message ID behave?

• It is required: a missing ID returns a 400 error with the code validation_failed.
• It is unique per API key, not per conversation.
• If the earlier request finished, sending the same ID again returns the saved result with a 200, adds no new message and does not call the assistant again.
• If the earlier request is still running, the API returns a 409 with operation_in_progress, so wait and send it again.
• If the earlier request failed, the same ID is processed as a fresh attempt.
• The content is not compared: the same ID with different text still returns the old result, so generate a new ID for every new message.

What does a request and response look like?

Call the API from your own server and never put a live key in browser or mobile code. Here $API stands for your API address, which the code samples on the API keys page already fill in.

curl -X POST $API/api/v1/public/chat \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Do you ship to Da Nang?",
    "clientMessageId": "chat-7f3a91c2"
  }'

The response, shortened:

{
  "conversationId": "...",
  "answer": "Yes, we deliver to Da Nang ...",
  "sources": [ ... ],
  "isFallback": false
}

Sending the exact same command again with the same clientMessageId returns this same response and creates no second message.

If you are thinking of keeping your own chat front end and only calling the API, read AI Chatbot vs building it yourself. The integrations page lists the ready-made channels, and the security page explains how data is protected.