Chat API
Errors
Every error is a JSON object with a single error string:
{ "error": "<message>" }The messages are written to be shown to a person, so an integration can pass them straight through.
HTTP status codes
| Status | Meaning |
|---|---|
200 | Success |
201 Created | The reply was sent (POST /api/v1/chats/{id}/reply) |
400 Bad Request | A missing or invalid field or query parameter, no valid rep to act as, or an action the conversation's state does not allow. Examples below |
401 Unauthorized | Missing, malformed, expired, or revoked API key |
403 Forbidden | The key lacks the scope: read:chat for GET, write:chat for everything else |
404 Not Found | No conversation with that ID in this workspace, or no such tag |
429 Too Many Requests | Rate limit exceeded |
Examples
Validation (400):
{ "error": "status must be one of: waiting, open, closed, spam, trash, all." }{ "error": "since must be an ISO 8601 datetime." }{ "error": "cursor is not valid. Pass the nextCursor value from the previous page unchanged." }{ "error": "body is required: the message to send to the visitor." }{ "error": "Messages can be up to 2,000 characters." }{ "error": "Pass tagId (an existing tag) or name." }Acting as a rep (400):
{ "error": "asUserId (or asUserEmail) is required to reply: name the workspace member the visitor will see." }{ "error": "asUserEmail \"sam@example.com\" is not a member of this workspace." }{ "error": "asUserId \"cmq1user9alk34567890\" is a deactivated user. Choose an active member of this workspace." }{ "error": "assigneeId \"cmq1user9alk34567890\" is not an active member of this workspace." }Conversation state (400):
{ "error": "Only the person handling this chat can hand it back." }Not found (404): an ID from another workspace returns the same error as one that does not exist.
{ "error": "Conversation not found." }{ "error": "Tag not found." }{ "error": "No tag named \"Pricing\" in this workspace." }Limits
| Limit | Value |
|---|---|
| Message length | 2,000 characters |
Messages per GET /api/v1/chats/{id} | 500 |
| Conversations per list page | 1,000 |
| Tag name | 40 characters |
| Spam block | 30 days |
Each API key is limited to 120 requests per minute (platform-enforced). Exceeding it returns 429 with a Retry-After header giving the seconds until the window resets. If you poll a live conversation, a poll every few seconds per conversation stays well inside that.