Chat realtime protocol (v1)

Every chat client (the web widget and the Flutter, React Native, iOS and Android SDKs) speaks the same WebSocket protocol with the gateway at chat.hatang.dev. Read this page to write your own client or to understand what the SDKs do under the hood. The frame tables further down are generated from the JSON Schema shipped with the @hatang/chat-protocol package, so they always match the gateway.

Machine-readable versions: chat.hatang.dev/protocol.json (version, limits, close codes, error codes) and the JSON Schema files visitor-frames.json, server-frames.json, http.json and protocol.json. What a native SDK must do on top of the protocol (session lifecycle, history, attachments, push) is checked by the conformance scenarios C01–C12 that every SDK passes before a release.

Envelope

Call POST /widget/v1/sites/{siteId}/bootstrap. It creates or refreshes the visitor token and returns ws_url. A browser needs an Origin allowed for the site; a native app sends its app key in the x-hatang-app-key header instead, and the token it gets back carries the app's id.
Open ws_url: wss://chat.hatang.dev/ws?site=<site_id>, plus &app=<app_id>&install=<install_id> for an app. Use it exactly as returned; an app socket needs no Origin.
Send auth as the first frame, within 5 seconds.

Every frame is a JSON object:

{ "t": "message.send", "id": "req_1", "v": 1, "d": { "client_id": "c_9f2", "content": "Is this still in stock?" } }

Key	Meaning
`t`	Frame type
`d`	Data
`v`	Protocol version (`1`)
`id`	Optional request id, echoed in `message.ack` or in `error.for` so you can match a reply to its request

Both sides send ping every 25 seconds and answer with pong. For the HTTP endpoints, send the visitor token in the x-visitor-token header. In the identify frame the user id field is user_id; every native SDK sends that name, and the web widget's $hatang API also accepts userId and maps it to user_id.

Ordering and resume

Every message and event in a conversation carries a seq that grows by one. Store the highest seq you have seen. After a reconnect (or right after ready when you already have one), send resume { conversation_id, after_seq }; the server replays everything after it from the database, so a frame lost while the socket was down is never lost for good. Load older history over HTTP with before_seq, and catch up with after_seq.

To send a message:

Generate a client_id for it and show the bubble as sending.
Send message.send and wait up to 10 seconds for message.ack.
On a timeout or an error, keep the bubble in a failed state and retry with the same client_id. The server answers a repeated client_id with the original message instead of creating a second one.
The message frame for your own message arrives too; dedupe it by id.

Close codes

Code	Meaning	What the client does
4001	No `auth` within 5 seconds	Reconnect and send `auth` first
4003	Authentication refused or session revoked (app key revoked, for example)	Stop; drop the token and bootstrap a new visitor
4004	The client's protocol is older than the gateway supports; a `reload` frame comes first	Browsers reload the page; native clients stop reconnecting and ask the user to update the app
4005	A `session` frame just carried a new visitor token (identity merge)	Reconnect at once with the new token
other	Network trouble, gateway restart	Reconnect with backoff `min(30 s, 500 ms · 2^n)` plus up to 500 ms of jitter

Error codes

HTTP errors are { statusCode, name, message }; socket errors are an error { code, message, for? } frame.

Code	HTTP	Meaning
`invalid_app_key`	401	The `x-hatang-app-key` header is missing, wrong or belongs to another site
`app_key_revoked`	403	The key was revoked in the dashboard; the app needs an update with a new key
`invalid_visitor_token`	401	The visitor token expired, was reset or was revoked; bootstrap again
`unauthenticated`	401	No token
`origin_not_allowed`	403	The browser's Origin is not allowed for this site
`site_disabled`	403	The site is turned off
`product_disabled`	403	The business has turned off the Customer Support module (Businesses and modules). The widget hides its button; the SDKs report the error when the chat starts and the rest of the app keeps working. Turning the module back on is enough to reconnect
`validation_error`	422	The data has the wrong shape or exceeds a limit
`rate_limit_exceeded`	429	See the rate limits below; try again later
`conversation_closed`	409	Sending into a closed conversation
`file_too_large`, `unsupported_file_type`	413, 422	Uploads: 10 MB at most; images (HEIC included), PDF, office files, zip, mp4 and m4a
`not_found`	404	The conversation, message or file does not belong to this visitor
`bad_frame`	—	The frame is not valid JSON or has no `t`

Rate limits:

What	Limit
Bootstrap	30 per minute per app install, or per IP address for browsers
Open sockets	3 at a time per app install
Visitor messages	5 per 10 seconds and 60 per minute per visitor
Uploads	10 per minute per visitor
Device registration	10 per minute per visitor

Rendering cards

A message whose metadata.kind is product, order, payment, quick_replies or csat carries structured data the client draws as a card: products, an order, a payment button, quick replies or a rating prompt. Its content is always plain text, so channels without cards can still read it. Tapping a quick reply sends its label as the visitor's message. csat invites a rating (stars in the widget, quick replies elsewhere), and the client answers with a rate frame. Unknown kinds are shown as plain messages. The shape of each card is in Cards in a message's metadata.

If you write your own client:

Text above a card. For product, order and payment cards, content is the full summary meant for email, push and other channels; do not show it in a bubble next to the card. Show only the intro line, metadata.intro, when there is one, and no bubble otherwise. quick_replies, csat and unknown kinds still show content.
VietQR code. qr_image_url is an SVG (/pay/{id}/qr.svg). Browsers draw it, but many mobile image loaders cannot. Draw the code yourself from qr_payload (the EMVCo string); for older cards without it, read qr.payload from the public GET /pay/{id}.
Paid state. The message holding a payment card is not updated when the customer pays. Treat the card as paid when its status is paid or succeeded, when the timeline has a message with metadata.kind = "order_paid" for the same order_id, or when an order_paid event has a matching data.payment_id or data.order_id. Then hide the QR code, the transfer note and the pay button.
Apps that sell digital goods. On iOS and Android, digital goods (courses, memberships and so on) must be sold through in-app purchase. The mobile SDKs have a HatangCommerce hook that hands the buy button to your in-app purchase code; physical goods keep VietQR.

HTTP endpoints

Every path below is under /widget/v1/sites/{siteId}/. The full OpenAPI is in the Chat gateway reference.

Endpoint	What it does
`POST bootstrap`	Creates or refreshes the visitor token. Returns `visitor`, `conversation`, `timeline`, `availability`, `ws_url` and the site config. Native SDKs send `app { install_id, version, sdk, os, os_version, device_model, locale }` and `screen`
`GET conversations?status=all\|open\|resolved&limit&after`	The visitor's conversations, resolved ones included, for an in-app inbox
`POST conversations`	Returns the visitor's active conversation, or opens a new one
`GET conversations/{id}/messages?before_seq&limit` or `?after_seq`	A page of older history, or a catch-up
`POST conversations/{id}/messages`	Send a message over HTTP, when no socket is available
`POST uploads`	Multipart `file`; returns `{ id, name, size, type }`. Then send `message.send { content: "", attachments: [id] }`
`PUT devices`, `DELETE devices`	Register or remove a push token (Push notifications)
`POST leads`, `POST offline-message`	A lead from a form; a message left outside office hours
`POST reset`	Forget the visitor; the old token stops working and a new one is returned
`POST sessions/restore`	Swap the token from a "we replied" email link (`/c/<token>`) for that visitor's session

Attachment URLs in attachments[].url are signed links to GET /files/{id}?exp&sig and stay valid for 24 hours. When one expires, load the message again to get a fresh link.

Limits and timing

Protocol version: 1.

Limit	Value
One frame	16384 B
Visitor message	4000 chars
Agent message	10000 chars
Attachments per message	5
One attachment	10 MB
Custom data (`identify.data`, `setData`)	8 KB
Send `auth` within	5 s
`ping` interval (both sides)	25 s
Wait for `message.ack` / a reply	10 s
Reconnect	`min(30 s, 500 ms · 2^n)` + jitter ≤ 500 ms; immediately after close codes 4005

Close codes: 4001 auth_timeout · 4003 auth_failed · 4004 protocol_outdated · 4005 session_replaced.

Error codes: validation_error, rate_limit_exceeded, not_found, unauthenticated, invalid_visitor_token, origin_not_allowed, site_disabled, invalid_app_key, app_key_revoked, conversation_closed, file_too_large, unsupported_file_type, bad_frame, error.

Visitor → server frames

`auth`

First frame, within 5 seconds of opening the socket. Browsers send page; native SDKs send screen, app and client. app_state lets a socket opened in the background avoid counting as online.