WebSocket API Reference#
Connection#
ws://your-chatapi-instance.com/ws
wss://your-chatapi-instance.com/wsAuthentication#
Browser clients#
Browsers cannot set custom headers on WebSocket connections. Pass the JWT as a query parameter:
const ws = new WebSocket(`wss://your-chatapi.com/ws?token=${jwt}`);Server-side clients#
Server clients can set the Authorization header during the WebSocket handshake:
Authorization: Bearer <jwt>Example (Node.js):
const WebSocket = require("ws");
const ws = new WebSocket("wss://your-chatapi.com/ws", {
headers: { Authorization: "Bearer <jwt>" },
});Connection lifecycle#
- Client connects with a JWT.
- Server validates the token and registers the connection.
- Server broadcasts
presence.update(online) to rooms the user belongs to. - Client fetches missed messages via
GET /rooms/{id}/messages?after_seq=<last_seen>for each room. - On disconnect, the server waits a grace period, then broadcasts
presence.update(offline).
Missed messages#
The server does not replay missed messages on reconnect. After reconnecting, poll each room for messages since your last known sequence number:
GET /rooms/{room_id}/messages?after_seq=<last_seen_seq>
Authorization: Bearer <token>Message format#
All frames are JSON objects with a type field.
Client → Server messages#
send_message#
Send a message to a room.
{
"type": "send_message",
"data": {
"room_id": "room_abc123",
"content": "Hello!",
"meta": "{\"mentions\":[\"bob\"]}"
}
}meta is optional.
ack#
Acknowledge all messages up to and including seq.
{
"type": "ack",
"data": {
"room_id": "room_abc123",
"seq": 43
}
}typing.start / typing.stop#
{"type": "typing.start", "data": {"room_id": "room_abc123"}}
{"type": "typing.stop", "data": {"room_id": "room_abc123"}}ping#
Keep-alive.
{"type": "ping"}Server → Client events#
message#
A new message was sent in a room the user belongs to.
{
"type": "message",
"room_id": "room_abc123",
"seq": 44,
"message_id": "msg_def456",
"sender_id": "alice",
"content": "Hello!",
"created_at": "2026-04-02T12:10:00Z"
}meta is included only when non-empty.
message.stream.start#
An LLM bot has begun streaming a response.
{
"type": "message.stream.start",
"room_id": "room_abc123",
"message_id": "msg_stream_789",
"sender_id": "bot_support"
}message.stream.delta#
A token chunk from a streaming LLM response.
{
"type": "message.stream.delta",
"room_id": "room_abc123",
"message_id": "msg_stream_789",
"delta": "Hello, how can I "
}message.stream.end#
Streaming complete. The full content is included and the message has been persisted with its sequence number.
{
"type": "message.stream.end",
"room_id": "room_abc123",
"message_id": "msg_stream_789",
"sender_id": "bot_support",
"content": "Hello, how can I help you today?",
"seq": 45
}message.stream.error#
The LLM call failed after the stream had already started. Discard any partial content accumulated for this message_id.
{
"type": "message.stream.error",
"room_id": "room_abc123",
"message_id": "msg_stream_789"
}ack.received#
Confirmation that an ACK was processed.
{
"type": "ack.received",
"room_id": "room_abc123",
"seq": 43,
"user_id": "alice"
}presence.update#
A user’s connection status changed.
{
"type": "presence.update",
"user_id": "bob",
"status": "online"
}status is "online" or "offline".
typing#
Another user started or stopped typing.
{
"type": "typing",
"room_id": "room_abc123",
"user_id": "bob",
"action": "start"
}action is "start" or "stop".
error#
Sent when a request is rejected. Currently emitted for rate limit violations.
{
"type": "error",
"data": {
"code": "rate_limited",
"message": "too many requests"
}
}server.shutdown#
Graceful shutdown notice. Reconnect after the indicated delay.
{
"type": "server.shutdown",
"reconnect_after_ms": 5000
}Reconnection#
Implement exponential backoff. For browser clients, the JWT is passed as a query param and is valid for the token’s exp claim, so refresh it if needed before reconnecting.
let delay = 1000;
function connect() {
const ws = new WebSocket(`wss://your-chatapi.com/ws?token=${getJWT()}`);
ws.onopen = () => { delay = 1000; };
ws.onclose = () => {
setTimeout(connect, delay);
delay = Math.min(delay * 2, 30000);
};
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
if (msg.type === "server.shutdown") {
setTimeout(connect, msg.reconnect_after_ms);
}
};
}
connect();Connection limits#
The server enforces a maximum of 5 concurrent WebSocket connections per user by default (configurable via WS_MAX_CONNECTIONS_PER_USER). Excess connections are rejected with a policy-violation close frame.