Control WebSocket

WS/v1/outputs/{id}/control/ws

Send an API key as a bearer token.

A live connection to an output. It tells you everything that changes as it happens, and takes the same commands as Run commands.

Connect

Open a WebSocket to the path above, on wss://. Browsers can't set headers on a WebSocket, so pass the API key as ?token=. From the server side, an Authorization: Bearer header works too.

What it sends

statemessage

First, the output's whole state, then again whenever the output loads another version. now is the output's clock in milliseconds, which timers are measured against.

patchmessage

Each change after that: revision and the update, holding only what changed, such as onAir, components data or timers. Apply them in order on top of the state.

showmessage

The version the output plays and its instances, on connect and whenever they change.

ackmessage

A batch you sent ran. Carries your batch's id and the new revision.

errormessage

A batch didn't run, or a message wasn't understood. Carries your batch's id and the failed command's index where there is one.

What you send

JSON

{ "type": "commands", "id": "take-1", "commands": [ … ] }

id is optional, and comes back on the ack or error so you can match them up. Batches over the socket follow the same rules as over HTTP: in order, all or nothing.

Reconnect when it drops.

Networks blip. When the socket closes, wait a moment and connect again: the first message is the whole state, so you're back in step straight away.