WebSocket API Reference

Low-level WebSocket protocol reference for NoLag real-time communication. Frames are shown as JSON for readability; on the wire the server always sends MessagePack binary frames.

Connection

Authentication

The first message sent after connecting must be an auth request. Any other frame sent before authentication is answered with { "type": "error", "error": "not_authenticated" }. The server sets no separate authentication deadline; only the 60-second idle timeout applies. The SDKs give up on their side if no auth reply arrives within 10 seconds.

{
  "type": "auth",
  "token": "at_live_<key_id>.<secret>",
  "protocolVersion": 2,
  "reconnect": false,
  "clientId": "worker-7",
  "projectId": "..."
}

Request fields:

Success response fields: actorTokenId, projectId, actorType, the negotiated protocolVersion, and restoredSubscriptions (empty unless reconnect was true). Each restored entry is { "pattern", "topic", "load_balance", "load_balance_group", "filters" }, where pattern is the app/room/topic address and topic is the broker's internal topic.

On failure the socket stays open; error is one of the strings listed under Authentication Errors.

Client to Server Messages

1. subscribe

Subscribe to a topic to begin receiving messages. Idempotent: subscribing again with different options switches the subscription in place.

{
  "type": "subscribe",
  "topic": "app/room/topic",
  "qos": 1,
  "filters": ["f1", ["region:eu", "tier:gold"]],
  "loadBalance": false,
  "loadBalanceGroup": "group-1"
}

The room must already exist; an unknown room, or one this actor may not access, returns 42940 unknown_topic. See Rooms.

2. unsubscribe

Stop receiving messages from a topic.

{
  "type": "unsubscribe",
  "topic": "app/room/topic"
}

3. publish

Publish a message to a topic.

{
  "type": "publish",
  "topic": "app/room/topic",
  "data": { "your": "payload" },
  "qos": 1,
  "echo": true,
  "retain": false,
  "filter": "f1",
  "msgRef": "17-k3j9x2"
}

Publishing is limited to 50 messages per second per connection (42910 rate_limit_exceeded).

4. setFilters

Replace the entire filter set for a subscription. Sending an empty array acts as a wildcard, meaning all messages will be received. Filter values follow the same rules as on subscribe. Sending this for a topic you have not subscribed to returns not_subscribed.

{
  "type": "setFilters",
  "topic": "app/room/topic",
  "filters": ["f1"]
}

5. presence

Announce or update presence data for a room. Presence is room-scoped; roomId is the room slug and must be a room the actor can access. Sending the frame again for a different room leaves the previous room first.

{
  "type": "presence",
  "roomId": "room-slug",
  "data": { "status": "online" }
}

A presence frame without roomId is deprecated: the server stores the data on the connection but broadcasts nothing.

6. getPresence

Request the current presence list for a room.

{
  "type": "getPresence",
  "roomId": "room-slug"
}

7. ack

Acknowledge receipt of a single message. Send it when the server delivers a message with requiresAck: true.

{
  "type": "ack",
  "msgId": "uuid"
}

8. batchAck

Acknowledge receipt of multiple messages at once.

{
  "type": "batchAck",
  "msgIds": ["id1", "id2"]
}

9. lobbySubscribe

Subscribe to a lobby to receive aggregated presence events across multiple rooms. A lobby the actor may not access returns { "type": "error", "error": "not_authorized", "lobbyId": "..." }.

{
  "type": "lobbySubscribe",
  "lobbyId": "lobby-slug"
}

10. lobbyUnsubscribe

Unsubscribe from a lobby.

{
  "type": "lobbyUnsubscribe",
  "lobbyId": "lobby-slug"
}

11. getLobbyPresence

Request the current presence data for an entire lobby.

{
  "type": "getLobbyPresence",
  "lobbyId": "lobby-slug"
}

12. reauth

Renew a client token on the live connection, without disconnecting or resubscribing. The new token must resolve to the same actor as the current connection. On success the connection's grants, limits and expiry are refreshed from the new token.

{
  "type": "reauth",
  "token": "<new client token>"
}

authExpiresAt (Unix seconds) is present when the new token carries an expiry. On failure the connection stays open under its current authentication; error is actor_mismatch, token_expired, or one of the authentication error strings.

Server to Client Messages

1. message

Delivers a published message to the client.

{
  "type": "message",
  "topic": "app/room/topic",
  "data": { "your": "payload" },
  "msgId": "uuid",
  "requiresAck": true,
  "isReplay": false,
  "filter": "f1"
}

2. subscribed

Confirms a successful subscription.

{
  "type": "subscribed",
  "topic": "app/room/topic",
  "loadBalance": false
}

3. unsubscribed

Confirms a successful unsubscription.

{
  "type": "unsubscribed",
  "topic": "app/room/topic"
}

4. published

Acknowledges a publish that carried a msgRef (protocol v2). The SDKs surface this as the publish callback. There is no resend on the WebSocket leg; a publish that is never acknowledged has to be repeated by the client.

{
  "type": "published",
  "topic": "app/room/topic",
  "msgRef": "17-k3j9x2"
}

5. filtersUpdated

Confirms that the filter set for a subscription has been updated.

{
  "type": "filtersUpdated",
  "topic": "app/room/topic",
  "filters": ["f1"]
}

6. presence

Notifies the client of a presence change in a room it has announced presence in. Note the snake_case keys, which differ from presenceList.

{
  "type": "presence",
  "event": "join",
  "data": {
    "actor_token_id": "...",
    "presence": { "status": "online" }
  }
}

The event field is one of "join", "leave", or "update". Events carry no joinedAt; that field is only on presenceList entries. The SDKs normalise actor_token_id to actorTokenId before handing the event to your code.

7. presenceList

Returns the full list of present actors in a room. Sent in response to a getPresence request.

{
  "type": "presenceList",
  "roomId": "room-slug",
  "data": [
    { "actorTokenId": "...", "presence": { "status": "online" }, "joinedAt": 1716000000 }
  ]
}

joinedAt is Unix seconds. A getPresence without roomId is deprecated and returns an empty data array.

8. lobbySubscribed

Confirms a lobby subscription and includes the current presence snapshot. The snapshot is keyed by room slug, then by actorTokenId; each inner value is a full presence entry.

{
  "type": "lobbySubscribed",
  "lobbyId": "lobby-slug",
  "presence": {
    "general": {
      "019fd987-a03a-70cf-9420-60538a186bbb": {
        "actorTokenId": "019fd987-a03a-70cf-9420-60538a186bbb",
        "presence": { "status": "online" },
        "joinedAt": 1716000000
      }
    }
  }
}

9. lobbyUnsubscribed

Confirms a lobby unsubscription.

{
  "type": "lobbyUnsubscribed",
  "lobbyId": "lobby-slug"
}

10. lobbyPresence

Notifies the client of a presence event within a lobby. roomId is the room slug; data is the actor's presence payload (empty on leave).

{
  "type": "lobbyPresence",
  "event": "join",
  "lobbyId": "lobby-slug",
  "roomId": "general",
  "actorId": "019fd987-a03a-70cf-9420-60538a186bbb",
  "data": { "status": "online" }
}

11. lobbyPresenceList

Returns the full presence data for a lobby, in the same shape as the lobbySubscribed snapshot. Sent in response to a getLobbyPresence request.

{
  "type": "lobbyPresenceList",
  "lobbyId": "lobby-slug",
  "presence": {
    "general": {
      "019fd987-a03a-70cf-9420-60538a186bbb": {
        "actorTokenId": "019fd987-a03a-70cf-9420-60538a186bbb",
        "presence": { "status": "online" },
        "joinedAt": 1716000000
      }
    }
  }
}

12. replayStart

Marks the beginning of a replay. Replay only happens for a load-balanced worker group with a persistent session that scaled to zero and is being woken; it does not happen on an ordinary reconnect. See Replay.

{
  "type": "replayStart",
  "count": 247
}

Live messages that arrive during a replay are buffered and delivered after replayEnd, deduplicated against the replayed ids.

13. replayEnd

Marks the end of a replay.

{
  "type": "replayEnd",
  "replayed": 247
}

14. hydration

Sent once per subscribe when a webhook is configured for the topic, either topicConfigs.<topic>.webhooks.onSubscribe or the app-level hydrationWebhook (the per-topic entry wins). topic is the bare topic name, not the full address; data is whatever the webhook returned. Hydration is best-effort: a failing webhook is logged and no frame is sent. See Webhooks.

{
  "type": "hydration",
  "topic": "messages",
  "data": { "initialState": "..." }
}

15. error

Reports an error to the client. Fields and codes are listed in the Error Reference.

{
  "type": "error",
  "error": "unknown_topic",
  "code": 42940,
  "topic": "app/room/topic",
  "hint": "room is not configured. Provision it via the control-plane rooms API before use."
}

16. disconnect

Informs the client that the server is about to close the connection. Sent only before a 4003 close, when a client token has expired; other server-initiated closes (4001, 4002) carry their reason in the close frame instead.

{
  "type": "disconnect",
  "reason": "token_expired"
}

QoS Levels

qos on subscribe and publish is validated (0, 1, 2; anything else becomes 1) and passed to the broker's internal MQTT hop. It does not change what happens on the WebSocket leg, where the only delivery signal is the optional published ack and there is no resend.

See QoS.

Reconnection

When a client reconnects after a disconnect, it sends the auth message with reconnect: true. The server restores the subscriptions it recorded for the actor (topic, filters, load-balance settings) and returns them in restoredSubscriptions. Nothing is replayed on an ordinary reconnect: messages published while the client was offline are gone unless the client is a member of a load-balanced worker group with a persistent session, in which case the replay flow runs.

Reconnection flow

1. Client reconnects and sends auth with reconnect: true (and the same clientId, if it uses one).
2. Server responds with restoredSubscriptions, an array of { "pattern", "topic", "load_balance", "load_balance_group", "filters" } objects, and resubscribes the connection to each.
3. Live delivery resumes.
4. For a woken load-balanced group only: replayStart, the replayed messages with isReplay: true, then replayEnd.

Backoff strategy

The SDKs use this schedule; a hand-rolled client should do something similar.

Each failed reconnection attempt increases the delay by the multiplier, up to the maximum. For example: 5s, 7.5s, 11.25s, 16.875s, 25.3s, 30s, 30s, ...

Next Steps

• Error Codes
• JavaScript SDK