Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jAtInn71/chatwoot-costom/llms.txt

Use this file to discover all available pages before exploring further.

The widget conversation API is a set of endpoints under /api/v1/widget/conversations that the embedded Chatwoot chat widget uses to manage visitor conversations. These endpoints operate in the widget namespace, which means they identify both the inbox and the visitor using the website_token query parameter rather than an agent API token. All endpoints require website_token to be present as a query parameter. The widget SDK handles calling these endpoints automatically when you embed the standard script tag — you only need to call them directly if you are building a custom integration on top of the widget layer.

​
Authentication

Every endpoint in this reference requires the website_token query parameter. This token is available from the Chatwoot dashboard under Settings → Inboxes → your inbox → Configuration → Installation. 
?website_token=YOUR_WEBSITE_TOKEN

​
List conversations

GET /api/v1/widget/conversations
Returns the current open conversation for the visitor identified by the contact auth token. The widget calls this endpoint on load and periodically to sync conversation state. Returns an empty payload when no conversation exists yet.

​
Create conversation

POST /api/v1/widget/conversations
Creates a new conversation for the current visitor. The widget calls this when the visitor sends their first message. This endpoint also processes contact identity — if the visitor has provided their name, email, or phone number, those fields are applied to the contact record during conversation creation. The request body accepts the initial message content, contact details, and optional metadata such as a referrer URL and a client-side timestamp.

​
Set custom attributes

POST /api/v1/widget/conversations/set_custom_attributes
Updates the custom attributes on the current conversation. Custom attributes are key-value pairs that you define in the Chatwoot dashboard. Use this endpoint to attach metadata to a conversation — for example, a plan tier, a user ID from your application, or a session property. Request body: { "custom_attributes": { "key": "value" } } Returns HTTP 404 if no open conversation exists.

​
Toggle typing indicator

POST /api/v1/widget/conversations/toggle_typing
Sends a typing indicator event to the dashboard so agents can see when the visitor is composing a message. The widget calls this automatically as the visitor types. Request body: { "typing_status": "on" } or { "typing_status": "off" } Returns HTTP 200. Returns HTTP 404 if no conversation exists.

​
Update last seen

POST /api/v1/widget/conversations/update_last_seen
Records the timestamp at which the visitor last viewed the conversation. The dashboard uses this to calculate which messages are unread from the visitor’s perspective and to update message read receipts. Request body: { "contact_last_seen_at": "<ISO 8601 timestamp>" } Returns HTTP 200. If no conversation exists the request is silently ignored.

​
Toggle conversation status

GET /api/v1/widget/conversations/toggle_status
Resolves the current conversation. This is used when the visitor clicks the end-chat button in the widget. The endpoint only resolves the conversation if the inbox has the end conversation feature enabled. Returns HTTP 403 if the inbox does not permit visitors to end conversations. Returns HTTP 200 on success.

​
Get signed URL for private voice agent

GET /api/v1/widget/conversations/voice_signed_url
Exchanges the inbox’s stored ElevenLabs API key for a short-lived signed WebSocket URL. The API key never leaves the server — only the signed URL is returned to the browser. The widget passes this URL to the ElevenLabs SDK when starting a session with a private agent.
This endpoint is only relevant for private ElevenLabs agents. Public agents do not require a signed URL and connect directly using their agent-id. If no API key or agent ID is configured on the inbox, this endpoint returns HTTP 422.
Returns { "signed_url": "wss://..." } on success.

​
Notes

The widget SDK handles all of these endpoints automatically. You do not need to call them directly unless you are building a custom integration outside of the standard embed script.
All endpoints use website_token captured at module load time from the original iframe URL. This makes requests immune to URL mutations that occur when the widget clears session parameters during soft exit (for example, after a visitor ends a chat).

Build docs developers (and LLMs) love

Get started for freeTalk to us