Realtime protocol

This page describes the wire protocol of the /v1/realtime/ws socket: getting a ticket, connecting, authentication, and the fields of every client and server frame. If you use the TypeScript SDK you do not write this protocol by hand; but read from here to understand the behavior, write another client, or troubleshoot.

Note

The protocol version is 1. Every frame carries protocolVersion: 1; any other value gets an UnsupportedProtocol error (versioning).

General rules

• Every frame is a JSON object sent as a single WebSocket text message. Binary messages are not accepted.
• The type field determines the frame type and is PascalCase (Authenticate, Join, …). The other field names are camelCase. A frame that contains an unknown field is rejected.
• Large integers (sequence numbers, epoch, revision, version) are decimal text, not JSON numbers: "sessionEpoch": "7". Canonical form: non-empty, no leading zero, digits only, non-negative, within the i64 range. Details: numbers and encoding. protocolVersion and schemaVersion are small integers and are sent as JSON numbers.
• requestId (UUID) is the correlation ID that the client generates for every attempt; the server returns the response and the error with the same ID.
• Before authentication only Authenticate is valid, and afterwards frames other than Authenticate are valid; a frame in the wrong phase gets UnexpectedFrame.

Connection flow

sequenceDiagram
    participant C as "Client"
    participant H as "HTTP (REST)"
    participant S as "WebSocket /v1/realtime/ws"
    C->>H: "POST /v1/realtime/tickets"
    H-->>C: "200 ticket, expiresAt"
    C->>S: "Upgrade (Sec-WebSocket-Protocol openplay.realtime.v1)"
    C->>S: "Authenticate(protocolVersion 1, ticket)"
    S-->>C: "Ready(connectionId, playerId, sessionEpoch, authorityGeneration)"
    C->>S: "Join(pluginId, moduleId, target)"
    S-->>C: "Joined(subscriptionId)"
    S-->>C: "Snapshot or DurableRecovery"
    C->>S: "Input or Command"
    S-->>C: "Ack or CommandResult"

1. Get a ticket

POST /v1/realtime/tickets HTTP/1.1
Host: game.example.com
Origin: https://game.example.com
x-crx-env: 0192a3b4-0000-7000-8000-000000000001
Cookie: __Secure-crx.session=<session>; __Secure-crx.csrf=<csrf-cookie>
x-csrf-token: <csrf-token>

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json

{"ticket":"tkt_AbC123-xyz","expiresAt":"2026-11-03T10:15:30+00:00","protocol":"openplay.realtime.v1"}

• The ticket is single-use, valid for 30 seconds, and bound to the Origin. Get it right before opening the socket; do not hold on to it.
• On this endpoint, identity, CSRF, and Origin errors get the same response: 403 and the plain text permission denied. If the module is disabled (plugins), 404 and {"code":"module_disabled",…}.

2. Open the socket

• Address: wss://<your-game-domain>/v1/realtime/ws. There must be no query string; if there is, the upgrade is rejected.
• Sec-WebSocket-Protocol: openplay.realtime.v1 must be requested; the server selects it. If it is not requested, the upgrade is rejected.
• Origin is required and must be one of the environment’s allowed origins or in the global allowed list. The browser sends it itself.
• An upgrade rejection is 401 (plain text unauthorized); if the module is disabled, 404.
• There are per-address and per-player connection limits (limits).

3. Send Authenticate

The first frame must arrive within 5 seconds after the socket opens; if it does not, the server writes an AuthenticationFailed error and closes. A frame in the authentication phase can be at most 4 KiB.

{"type":"Authenticate","protocolVersion":1,"ticket":"tkt_AbC123-xyz"}

The server consumes the ticket (verifying the origin and the subprotocol), re-verifies the session, and replies:

{"type":"Ready","protocolVersion":1,"connectionId":"0192a3b4-0000-7000-8000-0000000000a1","playerId":"0192a3b4-0000-7000-8000-0000000000b2","sessionEpoch":"7","authorityGeneration":"42"}

A ticket that is invalid, used, expired, or belongs to another origin is rejected with AuthenticationFailed; the server closes the socket. Get a new ticket and reconnect.

Client frames

They can be sent after Ready. The frame size is at most 16 KiB; a frame that exceeds it gets PayloadTooLarge.

Join: join a subscription

{"type":"Join","protocolVersion":1,"requestId":"0192a3b4-0000-7000-8000-000000000010","pluginId":"package-ride","moduleId":"package-ride.street","target":{"kind":"Scene","sceneId":"0192a3b4-0000-7000-8000-000000000031"}}

The server authorizes the target; a raw Redis key or topic name is not given. Success: Joined. After that, a Snapshot or DurableRecovery arrives depending on the module’s type.

Leave: leave a subscription

{"type":"Leave","protocolVersion":1,"requestId":"…","subscriptionId":"…"}

The response is Left; a repeated Leave is harmless.

Input: transient input

Player input (movement, steering) in server-authoritative modules. Loss is not acceptable, a sequence number is required.

{"type":"Input","protocolVersion":1,"requestId":"…","pluginId":"arena","moduleId":"arena.movement","messageType":"arena.movement.input","schemaVersion":1,"subscriptionId":"…","sessionEpoch":"7","inputSeq":"42","payload":{"delta":1}}

The input rate is defined by the ratePerSecond and burst values in the module’s schema document; a general per-connection frame budget is applied separately (limits).

Command: durable command

A command that writes durably with a database transaction (reward, delivery); the result returns only after the transaction is committed. It is subject to the same rules as the HTTP command endpoint (calling plugins).

{"type":"Command","protocolVersion":1,"requestId":"…","pluginId":"package-ride","moduleId":null,"messageType":"package-ride.progression-missions.claim.input","schemaVersion":1,"idempotencyKey":"claim-7f3a","expectedVersion":"12","payload":{"missionId":"daily-1"}}

Ping

{"type":"Ping","protocolVersion":1,"nonce":"a1"}

The response is {"type":"Pong","nonce":"a1"}. nonce is optional. The application-level Ping measures connection liveness; it does not count as player activity and does not postpone idle close (idle close).

Server frames

Ack statuses

revision may be absent other than for Applied and Replayed. When the field is absent, null is not sent; the field is simply not there.

Snapshot and DurableRecovery

• A Snapshot is transient state: streamEpoch (increases when the server cache restarts) and revision (monotonic) are ordered together. Within the same streamEpoch, an older revision must not overwrite the new state. If streamEpoch has changed, a new stream has started; do not compare with the old revision.
• DurableRecovery is the baseline in a durable stream: cursor is the new cursor tied to this point, barrierSequence is the stream start covered by the snapshot and the replay, and coveredEventIds are the event IDs that the snapshot already contains (do not apply them separately). snapshot is filled only on a fresh Join; it is absent when resuming with cursor.
• DurableEvents arrive in sequence order; eventId is the end-to-end deduplication key, and cursor is the new cursor advanced up to that event. Store the cursor: when reconnecting you provide it as Join.cursor (reconnect).

Error frame

{"type":"Error","requestId":"0192a3b4-0000-7000-8000-000000000010","code":"InvalidPayload","retryable":false}

The error frame carries no reason text: only the code and retryable. Even a plugin rejection (for example a business rule) appears as InvalidPayload; the reason is not given to the client over the wire.

Warning

Do not infer whether the socket will close from retryable alone. After an Error frame, the client must learn whether the socket is still open from the connection state (the close event). On long-lived sockets, per-frame errors (InvalidPayload, PermissionDenied) do not drop the connection.

Close codes

Example: connecting by hand (summary)

In the browser, use the SDK; the skeleton below shows the protocol order.

const res = await fetch("/v1/realtime/tickets", {
  method: "POST",
  credentials: "include",
  headers: { "x-crx-env": environmentId, "x-csrf-token": csrfToken },
});
const { ticket } = await res.json();
const ws = new WebSocket(`wss://${location.host}/v1/realtime/ws`, ["openplay.realtime.v1"]);
ws.onopen = () => ws.send(JSON.stringify({ type: "Authenticate", protocolVersion: 1, ticket }));
ws.onmessage = (event) => {
  const frame = JSON.parse(event.data as string);
  if (frame.type === "Ready") {
    // Send Join, store frame.sessionEpoch for Input frames.
  }
};

Next step

For how to resume with the cursor and epoch when the connection drops, limits, and compression, see reconnect and limits.