Connect to WebSocket delivery

A delivery is a configured channel that selects objects and routes their state updates to consumers. Deliveries decouple publishers from subscribers: publishers write state over HTTP, while deliveries decide who receives each update.

Open a WebSocket to the delivery host, authenticate, subscribe to a delivery identifier, and receive matching object create, update, and delete events as JSON frames.

Configure the delivery first with Create or update a delivery using channel type 1 (WebSocket). Publish state with Set object state. For a guided SDK path, see Deliver and read state.

Use a restricted subscriber credential

Credentials in browser JavaScript are visible to users.

Configure deliveries in a trusted environment. Give browser sockets only the permission to connect and receive matching updates.

wss://{{wsHost}}/v1?apiKey={{apiKey}}

How it works#

A WebSocket delivery connection follows a short lifecycle. Configure the delivery over HTTP first, then open the socket and subscribe.

Open

wss://ws.delivery.bigstate.dev/v1

with an API key or session token in the query string.

When the socket opens, send a

delivery.listen

frame for each delivery identifier.

Handle incoming frames:

type: 1

for object events,

type: 4

for errors.

Close with code

3001

when the disconnect is intentional.

Connect#

Connect to the delivery host with either an API key or a session token in the query string — provide exactly one.

With API key


wss://ws.delivery.bigstate.dev/v1?apiKey=YOUR_RESTRICTED_API_KEY

With session token


wss://ws.delivery.bigstate.dev/v1?auth=YOUR_SESSION_TOKEN

Query parameters#

RequiredOptional

apiKeystring
Optional
API key used to authenticate the socket. Provide either `apiKey` or `auth`.
example: {{apiKey}}
authstring
Optional
Session token used to authenticate the socket. Provide either `apiKey` or `auth`.
example: {{token}}

After the socket opens, send one JSON text frame per delivery identifier.


{
  "type": 2,
  "payload": {
    "command": "delivery.listen",
    "args": "deliveryWsQuickstart"
  }
}

•

type — 2 (client command)

•

payload.command — delivery.listen

•

payload.args — delivery identifier to subscribe to

Incoming messages#

The server pushes JSON frames. Check the message type, then read the payload.

Event — type 1

Delivered when a matching object is created, updated, or deleted.


{
  "type": 1,
  "payload": {
    "action": 2,
    "owner": "YOUR_OWNER",
    "object": "quickstart:counter@YOUR_OWNER",
    "state": {
      "at": "2026-07-17T12:00:00.000Z",
      "version": 12,
      "type": 2,
      "value": { "count": 42 }
    }
  }
}

•action

: 1 create, 2 update, 3 delete

•object

: fully qualified object name

•state

: optional snapshot with at, version, type, and value or valueRef

Error — type 4

Returned for a failed subscribe command or a delivery failure.


{
  "type": 4,
  "payload": {
    "error": "Delivery not found",
    "code": 404,
    "description": "No delivery exists for the given identifier.",
    "requested": {
      "type": 2,
      "payload": {
        "command": "delivery.listen",
        "args": "missingDelivery"
      }
    }
  }
}

Close and reconnect#

Close with code 3001 for an intentional disconnect. The JavaScript client treats that as a clean stop and does not reconnect. Any other close is treated as unexpected; the SDK reconnects and resubscribes automatically.

Delivery Tutorial