Post a chat message with the Public API

Short summary

Use this Public API endpoint to post a new Message from a Recipient into a Document chat. You can also generate an AI reply in the same request.

When to use this feature

Use this endpoint when you need to:

• add a Recipient Message to a Document chat
• post a message and get an AI reply in one API call
• trace or deduplicate client-side requests with "client_message_id"

Step-by-step instructions

1. Send a POST request to "/v2/public/documents/{document_id}/chat/messages".

1. Add the "Authorization" header with a bearer token:

   - "Authorization: Bearer <token>"

1. Replace "{document_id}" with the target Document ID.

1. Include a JSON body with:

   - "recipient_id"

   - "mode"

   - "message_text"

   - optional "client_message_id"

1. Set "mode" to "human" to store only the Recipient Message.

1. Set "mode" to "ai" to store the Recipient Message and generate an AI reply in the same thread.

1. Send the request. If successful, the API returns "201 Created" with the created message data.

Notes & limitations

• "recipient_id" is required.
• "message_text" is required.
• "message_text" must be non-empty after trimming.
• "message_text" supports 1 to 8000 characters.
• "mode" must be "human" or "ai".
• The Recipient must belong to the Document.
• Access can be denied if the token is missing, invalid, mismatched, or not allowed.
• A duplicate "client_message_id" can return "409 duplicate client_message_id".

Troubleshooting

Why did I get "400 invalid input"?

This happens when:

• a required field is missing
• "mode" is invalid
• "message_text" is empty after trimming

Why did I get "401 invalid/missing token"?

Your bearer token is missing or invalid.

Why did I get "403 not allowed"?

This happens when:

• the token company does not match
• the Recipient is not allowed

Why did I get "404 document or recipient not found on document"?

The Document was not found, or the Recipient was not found on that Document.

Why did I get "409 duplicate client_message_id"?

The "client_message_id" was already used and duplicate enforcement applied.

Why did I get "429 rate limit"?

The request limit was exceeded.