Building a website chat? The chat SDK handles this protocol for you. For signed-in customers, see Logged-in users. This page describes the raw WebSocket protocol for custom clients.
This is for connecting a client — typically a browser — to one specific session, in addition to your server-to-server integration with
POST /v1/chat/inbound. It’s not a replacement for the REST API.1. Mint a token
CallPOST /v1/chat/session/{id}/ws_token with your API-Token to get a short-lived token and the URL to connect to:
With an
API-Token, stream must be "user" — a 403 is returned for any other value. The session must not be closed (409 session_closed); a dormant session can still be minted for, since the next customer message reactivates it.2. Connect
Open the WebSocket atws_url exactly as returned (don’t build the host yourself), adding token and your own client_id as query parameters:
3. Send frames
Send JSON text frames. These shapes are accepted:typedefaults to"message"if omitted.message_idis optional — a client-chosen id echoed back on the acknowledgement, useful for matching a send to its ack in your UI.idempotency_keyis also accepted on every frame shape and behaves the same as onPOST /v1/chat/inbound/async— resending the same key and content is safe.attachmentsends a photo or PDF uploaded first; see Sending a file.contentis then the caption and may be empty.- For interaction responses, send
option_id(a button/list/carousel choice) orresponse(free-form input like a date), matching what the interactive message asked for — see Interactive messages. - Only text frames are accepted; sending binary data closes the connection.
4. Read acknowledgements and events
Every frame you send gets exactly one acknowledgement back:payload carries the same fields and state values as the synchronous Send Message response — reply, mode, and help_requested. A few states are specific to the socket:
Every ack echoes
message_id back if your frame included one, and carries turn_id once a turn exists for it.
Events
Beyond acknowledgements, the connection pushes events as they happen in the session:
Every event is wrapped as
{ type, session_id, account_id, ts, event_id, payload }. Use event_id to de-duplicate — a reconnect can replay a short window of recent events so you don’t miss anything that happened while briefly disconnected.
Sending a file
When the agent accepts files from visitors, a client can send one photo or PDF per message. Bootstrap and the session snapshot then carryagent.attachments, for example { "kinds": ["image", "document"], "max_bytes": { "image": 5242880, "document": 10485760 } }. Without it, files are refused; hide your attach button.
Sending takes two steps: upload the file, then send a message frame that names the upload.
1. Upload the file
file. The bearer token is the session’s user stream token from step 1. The file’s type is read from its bytes; its name and content type are ignored for that.
On success the response is
201:
upload_id cannot be sent in another one.
2. Send the message
Send amessage frame with attachment: { upload_id }, as in the Message with a file example above. Use an idempotency_key: a resend with the same key and upload is safe.
If the file cannot be accepted, the ack’s state is invalid with one of these errors:
A
busy ack (server_busy) means nothing was accepted; resend the same frame.
What comes back
Themessage_received event for the visitor’s message carries attachment: { kind, mime, filename?, size, state: "pending" }, with the caption alone as content. It has no link. Once the file is processed, history rows carry attachment: { kind, mime, filename, size, state, url }. url is a signed link on the API host that lasts about an hour, and is null while the file is processing or after it has been deleted (90 days). The agent replies as usual.
Close codes
Reconnecting
- On an unexpected drop, reconnect with exponential backoff — roughly 1s, 2s, 4s, 8s, up to a 30s cap — and give up after a handful of attempts, surfacing an error in your UI.
- Mint a new token ahead of the 5-minute expiry rather than waiting for the connection to be closed, so an active conversation doesn’t interrupt the customer.
- Reuse the same
client_idacross reconnects (persist it locally, e.g. insessionStorage) so you resume as the same client. Only sendclaim=1when the user explicitly wants to take over from another tab/session holding the connection — not on every routine reconnect, or you’ll evict yourself on the next tab. - On a
1008close with the agent inactive, don’t reconnect immediately in a tight loop — poll less aggressively (e.g. every 20s) until the agent is active again. On a1008close from a claim conflict, don’t auto-reconnect at all — surface a “Resume here?” action and only reconnect withclaim=1if the customer confirms.
