WebSocket protocol

The @cariosan/client SDK shields you from these details, but if you're building a client in a language we don't ship (Swift, Kotlin, Rust), here's the wire protocol in full.

Connection

wss://chat.example.com/v1/ws
Sec-WebSocket-Protocol: cariosan.jwt.<token>

The JWT comes from IssueUserToken on the Go SDK (or the REST POST /v1/users/:id/token equivalent). The token travels in the Sec-WebSocket-Protocol upgrade header so it never lands in reverse-proxy access logs or Referer headers.

The connection closes with code 4401 when its JWT expires, even if heartbeats continue. To keep it open, send a fresh token with auth.renew before then; otherwise obtain a fresh user token through your authenticated backend and reconnect. A token that is already invalid when you connect is refused during the upgrade with HTTP 401. Browsers and React Native cannot read that status and report a close with code 1006, the same as a network error. Expiry does not implement logout/session revocation. Revoking a user's tokens through the API closes their open connections with the same code: a revoked client's next incoming frame is rejected immediately, and an idle or receive-only connection is closed within about 5 seconds. If the revocation store is briefly unreachable, open connections are kept for up to 60 seconds before being closed; new connections fail closed immediately, with 503 and error.code AUTH_UNAVAILABLE (and a Retry-After header) rather than 401, so a client retries instead of treating its token as rejected. REST requests made with a user token behave the same way.

Browsers send this by passing the protocol string as the second argument to new WebSocket(url, "cariosan.jwt.<token>"); curl, wscat, and other CLI clients can set the header directly.

On successful upgrade, the server echoes the same protocol back per RFC 6455 and immediately sends a connection.ready frame.

Frame envelope

Every frame in either direction is JSON with this shape:

{ "type": "<event name>", "data": { ... } }

data is optional for events that need no payload (ping, pong).

An optional integer v may precede type ({ "v": 2, "type": ... }). It is omitted for v1 (today's protocol) and is only set if a payload ever changes incompatibly. Forward-compatibility contract: a client MUST ignore event types it doesn't recognise and unknown fields within a payload — so new event types and new optional fields never break an older client.

Client → Server events

ping

Heartbeat. Send every 30s. The server closes the connection after 90s of silence.

auth.renew

Hands the open connection a fresh token so it outlives the one it was opened with. No reconnect is needed, so presence does not flap and no frames are missed. The official SDK sends it automatically before the current token expires (see Tokens).

{
  "type": "auth.renew",
  "data": { "token": "eyJhbGciOiJIUzI1NiI...", "request_id": "renew_1" }
}

The server verifies the token like a new connection's, including revocation. It accepts the token only if it names the same user in the same workspace and expires no earlier than the current one. The connection then expires when the new token does, and revocation checks run against it. The server answers with auth.renewed, or with an error frame whose client_message_id echoes request_id:

A rejected token changes nothing: the connection keeps its current token and still closes with 4401 when that one expires. A server older than this frame answers UNKNOWN_EVENT (without a client_message_id); reconnect with the new token instead.

{ "type": "ping" }

message.send

Post a message. Equivalent to POST /v1/channels/:id/messages.

{
  "type": "message.send",
  "data": {
    "channel_id": "order_123",
    "content": "Halo",
    "type": "text",
    "attachment_url": null,
    "client_message_id": "0b7c1f9e-4d2a-4c8e-9a51-6f3e2d1c0b9a",
    "parent_id": "01HX...",
    "mentions": ["user_andi"]
  }
}

The server validates membership, size, attachment URL, and rate limit the same way it does for REST. Success responds with a message.ack; failure responds with an error frame. Both echo client_message_id, so you can match the reply to the frame you sent.

client_message_id is the send's idempotency key when it is a UUID, the same as on REST. Generate one per message and reuse it when you resend after a lost message.ack. The retry then acks the message that is already stored ("replayed": true). Nothing is stored or broadcast a second time, and the retry does not count against the rate limit again. A key is bound to the channel it was first used in; reusing it in another channel returns an IDEMPOTENCY_KEY_REUSED error frame. Any other value, such as "tmp_abc", is only echoed back and gives no protection against duplicates, which was the behaviour before this change.

parent_id is optional — set it to send a quoted reply. The parent must be in the same channel (otherwise a VALIDATION_ERROR frame), and the broadcast message.new embeds a quoted_message preview.

mentions is an optional list of channel members' external_ids to @-mention. Each must be a member (else a VALIDATION_ERROR frame); the broadcast message.new carries the resolved mentions array and each mentioned user receives a notification.mention on their own topic.

channel.read

Marks the channel as read up to now. The server stamps last_read_at and broadcasts a channel.read receipt to other members (subject to the workspace's read-receipts toggle).

{ "type": "channel.read", "data": { "channel_id": "order_123" } }

channel.delivered

Acks that this client has received the channel's messages (drives ✓✓ grey). The SDK sends this automatically on every inbound message.new; you rarely send it by hand. The server stamps last_delivered_at and broadcasts a channel.delivered receipt.

{ "type": "channel.delivered", "data": { "channel_id": "order_123" } }

typing.start / typing.stop

{ "type": "typing.start", "data": { "channel_id": "order_123" } }
{ "type": "typing.stop",  "data": { "channel_id": "order_123" } }

Client debounce responsibility: emit typing.start at most once per 2s, auto-emit typing.stop after 2s idle.

Server → Client events

pong

Reply to ping.

{ "type": "pong", "data": {} }

connection.ready

Sent once immediately after upgrade.

{
  "type": "connection.ready",
  "data": { "user_id": "uuid", "connected_at": "2026-04-17T10:00:00Z" }
}

message.new

A new message in a channel the user belongs to. Delivered via Redis pub/sub — works across multiple Cariosan server instances.

{
  "type": "message.new",
  "data": {
    "id": "msg-uuid",
    "channel_id": "chan-uuid",
    "user": { "id": "uuid", "external_id": "user_abc", "name": "Alice" },
    "content": "Halo",
    "type": "text",
    "metadata": {},
    "created_at": "2026-04-17T10:00:00Z"
  }
}

A reply additionally includes parent_id and a quoted_message preview ({ id, user_id, user_name, content, type, deleted }). A message with @-mentions includes a mentions array ([{ user_id, external_id, name }]). A message that was sent with an idempotency key includes client_message_id (the UUID the sender attached), which the sender's client uses to recognise its own message and retire the matching pending entry; it is not a secret. All of these are omitted when absent — per the forward-compatibility contract, ignore fields you don't recognise.

notification.mention

Delivered to a user's own topic (not the channel topic) when they're @-mentioned, so they're alerted even when not viewing the channel. Drives an in-app badge today; push delivery arrives in a later phase.

{
  "type": "notification.mention",
  "data": {
    "channel_id": "chan-uuid",
    "message_id": "msg-uuid",
    "by_user_id": "sender-uuid"
  }
}

message.updated

A message was edited. Broadcast to the channel; the message's content and edited_at change.

{
  "type": "message.updated",
  "data": {
    "id": "msg-uuid",
    "channel_id": "chan-uuid",
    "content": "edited text",
    "edited_at": "2026-04-17T10:05:00Z"
  }
}

message.deleted

A message was unsent. Render it as a tombstone — no content is included.

{
  "type": "message.deleted",
  "data": {
    "id": "msg-uuid",
    "channel_id": "chan-uuid",
    "deleted_at": "2026-04-17T10:06:00Z"
  }
}

message.reaction.add / message.reaction.remove

A member added or removed an emoji reaction on a message.

{
  "type": "message.reaction.add",
  "data": {
    "message_id": "msg-uuid",
    "channel_id": "chan-uuid",
    "user_id": "uuid",
    "emoji": "👍"
  }
}

message.ack

Reply to a successful message.send.

{
  "type": "message.ack",
  "data": {
    "client_message_id": "0b7c1f9e-4d2a-4c8e-9a51-6f3e2d1c0b9a",
    "server_message_id": "msg-uuid",
    "channel_id": "order_123",
    "created_at": "2026-04-17T10:00:00Z"
  }
}

A retried send adds "replayed": true. server_message_id and created_at then describe the message stored by the first send, the counterpart of REST's Idempotent-Replayed: true header. The field is omitted on a first send.

{
  "type": "message.ack",
  "data": {
    "client_message_id": "0b7c1f9e-4d2a-4c8e-9a51-6f3e2d1c0b9a",
    "server_message_id": "msg-uuid",
    "channel_id": "order_123",
    "created_at": "2026-04-17T10:00:00Z",
    "replayed": true
  }
}

auth.renewed

Reply to an accepted auth.renew. expires_at is the connection's new expiry, the new token's exp.

{
  "type": "auth.renewed",
  "data": { "request_id": "renew_1", "expires_at": "2026-10-11T10:20:00Z" }
}

typing.start / typing.stop

Broadcast to other members of the channel. The originating user never receives their own typing events.

{
  "type": "typing.start",
  "data": { "channel_id": "chan-uuid", "user_id": "uuid" }
}

channel_id is the channel's server id (UUID), like every other server event; the SDK maps it to your external_id. The client → server frame uses your external_id.

channel.read (receipt)

Broadcast to other members when a member reads the channel, so senders can flip to ✓✓ blue. Origin-filtered (the reader never receives their own). Suppressed when the workspace has read_receipts_enabled = false.

{
  "type": "channel.read",
  "data": { "channel_id": "chan-uuid", "user_id": "uuid", "read_at": "2026-04-17T10:00:00Z" }
}

channel.delivered (receipt)

Broadcast to other members when a member's client acks delivery (✓✓ grey). Origin-filtered. Never gated by the read-receipts toggle.

{
  "type": "channel.delivered",
  "data": { "channel_id": "chan-uuid", "user_id": "uuid", "delivered_at": "2026-04-17T10:00:00Z" }
}

channel.resync

The server detected that realtime events for a channel may have been lost while your socket stayed connected (a full per-channel buffer, or a failed publish to the Redis bus), so your view could be stale even though you never disconnected. Re-read recent history and reconcile it; see Staying in sync. It carries no message content, and it is only sent to members who are currently in the channel.

{
  "type": "channel.resync",
  "data": { "channel_id": "5f1d2c6e-…", "reason": "inbox_full" }
}

channel_id is the channel's server id (the SDK maps it to your external_id). reason (inbox_full, publish_failed or authz_unavailable) is diagnostic only: do not branch on it. A burst of losses is coalesced into a leading frame plus at most one trailing frame per second.

presence.update

Sent to every user who shares at least one channel with the subject.

{
  "type": "presence.update",
  "data": {
    "user_id": "uuid",
    "status": "online",
    "last_seen_at": "2026-04-17T10:00:00Z"
  }
}

error

Sent when a client frame fails validation or the server can't satisfy it.

{
  "type": "error",
  "data": {
    "code": "NOT_A_MEMBER",
    "message": "you are not a member of this channel",
    "client_message_id": "tmp_abc"
  }
}

Error codes: INVALID_JSON, UNKNOWN_EVENT, VALIDATION_ERROR, NOT_A_MEMBER, CHANNEL_NOT_FOUND, CHANNEL_FROZEN, MUTED, MESSAGE_REJECTED, RATE_LIMITED, QUOTA_EXCEEDED, SERVICE_UNAVAILABLE, IDEMPOTENCY_KEY_REUSED, UNAUTHORIZED, TOKEN_EXPIRED (the last two only answer auth.renew), INTERNAL_ERROR.

Three codes mean "try again later". They carry retry_after_seconds, the WebSocket counterpart of REST's Retry-After header. Wait at least that long before resending the frame:

None of them stores the message, so resending the same frame is safe. With a UUID client_message_id it is safe in every case, even when you are unsure whether the first attempt went through.

{
  "type": "error",
  "data": {
    "code": "QUOTA_EXCEEDED",
    "message": "workspace daily quota exceeded for messages_per_day",
    "client_message_id": "0b7c1f9e-4d2a-4c8e-9a51-6f3e2d1c0b9a",
    "retry_after_seconds": 3600,
    "details": { "metric": "messages_per_day", "limit": 1000, "current": 1000, "reset_at": "2026-04-18T00:00:00Z" }
  }
}

shutdown

Sent once before the server closes every connection on SIGTERM. Consumers should reconnect after a short delay.

{ "type": "shutdown", "data": { "reason": "server shutting down" } }

Close codes

Reconnect behaviour

The official SDK auto-reconnects on unexpected closes with exponential backoff (1s → 30s). Rolling your own client should do the same; the server is stateless, so you can reconnect mid-session and resume immediately.

A reconnect with an expired or revoked token fails the upgrade, which a browser reports as close code 1006, indistinguishable from a network failure. Do not retry forever with that token. Check the token's exp, or make one cheap authenticated REST request (a 401 confirms the token is the problem), and get a fresh token before the next attempt. The official SDK does this.