Post a message

POST /api/v1/public/conversations/{id}/messages

Records a message from the end user on the conversation the visitor token owns. The message lands in the agent's inbox immediately.

Authentication

Visitor token: Authorization: Bearer vt_….

Same scoping as List messages: the token works only against its own conversation.

Path parameters

Parameter	Type	Description
`id`	uuid	The `conversation_id` the token was minted for.

Field	Type	Required	Description
`body`	string	yes	The message text.

There is no way to attach a file to a Public API message — no attachment_ids, no multipart variant, and no separate upload endpoint. File attachments exist only in the widget. If your users need to send screenshots, weigh that before committing to a Public API chat UI.

Response

201 Created. data is the created message, in the same shape List messages returns.

{
  "success": true,
  "request_id": "6d7979ce52075b24979cd5b415319339",
  "data": {
    "id": "019f1c52-3333-7a80-91b2-c3d4e5f60718",
    "author": "customer",
    "body": "Any update?",
    "created_at": "2026-07-11T10:30:00.000000Z"
  }
}

author is always customer here — this endpoint can only ever speak for the end user.

Errors

Status	`error.code`	When
`400`	`BAD_REQUEST`	`id` is not a valid UUID.
`401`	`UNAUTHORIZED`	The visitor token is missing, unknown, expired, or revoked (`the visitor token is invalid`).
`404`	`NOT_FOUND`	The token does not own a conversation with this ID.
`422`	`VALIDATION_ERROR`	`body` is missing or empty. See `error.details`.
`429`	`RATE_LIMITED`	This token's budget is exhausted — 60 requests/minute by default, per token.

A successful post slides the token's 30-day expiry window forward. See Lifetime.

Examples

curl -X POST "{BASE_URL}/api/v1/public/conversations/019f1c4d-6e7f-7a80-91b2-c3d4e5f60718/messages" \
  -H "Authorization: Bearer vt_example_7Jq4Xm2Pz9Ln6Rd3Wb5T" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Any update?" }'