Send a visitor message

POST 
/api/widget/messages

PUBLIC endpoint (anonymous visitors, NO staff auth). Sends a message in the visitor's OWN conversation (taken from the verified session token, never the client). The message is always authored as sender_type=contact on the chat channel — these are SERVER-set and cannot be overridden, so a visitor cannot spoof a staff/bot message or target another conversation.

Because the author is a contact, the workspace's AI auto-reply pipeline may be triggered exactly like any other inbound message. Visitors may only send plain text, image and file blocks; staff-only interactive blocks (buttons, card, slider, translation) are rejected (422).

Request

Responses

201

The created message (visitor-facing shape).

403

Missing / invalid / cross-tenant session token, OR the conversation is blocked (the conversation status is blocked or the contact is blocked) — a blocked visitor cannot post.

404

Unknown or missing widget_key, or the conversation is gone.

422

The request failed validation.

429

Rate limit exceeded.

Response Headers

X-RateLimit-Limit

Request quota for the current window.

X-RateLimit-Remaining

Remaining requests in the current window.

Retry-After

Seconds to wait before retrying.