DocsReferenceClient protocolWebSocket gateway

WebSocket gateway

How the client protocol travels over a WebSocket: the upgrade and how it's refused, frames, keepalive and close codes. Registration, login and the messages themselves are the same for every gateway, so they're on the protocol page.

Address wss://ws.dev.wbskt.com/wsSubprotocol wbskt.v1

1. Connect

Open the WebSocket with the access token from login, and offer the wbskt.v1 subprotocol.

upgrade request
GET /ws HTTP/1.1
Host: ws.dev.wbskt.com
Upgrade: websocket
Authorization: Bearer <accessToken>
Sec-WebSocket-Protocol: wbskt.v1
  • A client that can't set headers on the upgrade, like a browser, puts the token in ?access_token= instead.
  • A connection that offers no subprotocol is treated as v1. One that offers only other versions is refused.
  • Send capabilities as soon as it opens, before anything else.

2. When the upgrade is refused

The gateway answers before upgrading, with a Problem Details body whose code says why.

AnswerMeansDo
401The token is expired, missing or not ours.Drop it and log in again.
401CLIENT_TOKEN_INVALIDThe token is missing something a client token needs.Drop it and log in again.
403It's a token, but not a client's.Use the token from client login. A bug, not something to retry.
403CLIENT_REVOKEDThe client was revoked, deleted or had its secret rotated since the token was issued.Keep the token and retry on the schedule. Once it expires, login says what happened.
400SOCKET_PROTOCOL_UNSUPPORTEDOnly subprotocol versions this gateway doesn't speak were offered.Offer wbskt.v1.
400SOCKET_UPGRADE_REQUIREDThe request wasn't a WebSocket upgrade.A bug, not something to retry.
503, or no answerThe gateway is restarting or unreachable.Keep the token and retry on the schedule.

3. Frames

Every message, both ways, is one text message holding one JSON object. It may arrive as several frames; the 64 KB limit is for the whole message. Binary frames are ignored.

4. Keepalive

Answer the protocol's sys.ping with sys.pong like any other message. Separately, the gateway sends a WebSocket Ping frame every 30 seconds and drops a connection that hasn't answered within another 30, so a board that lost power doesn't stay "online" for minutes. WebSocket libraries answer those Pings on their own.

5. Close codes

How this gateway says why it ended a connection. Branch on the code, not on the description.

CodeReasonDo
1000NormalReconnect on the schedule.
1001RestartingReconnect after a random 0–30 s.
1009Too bigA message was over 64 KB. Fix the sender.
1011Server errorReconnect on the schedule.
4001SupersededThe same client connected again. Repeated, it means shared credentials.
4002RevokedDrop the token; the next login says what happened.
4003ThrottledWait a random 30–60 s and send less.
4000from clientUpdatingSent by a client closing to install firmware. Shown as updating, not offline, for 5 minutes.
Older gatewaysBefore codes 4001–4003, all three were sent as 1008. Treat 1008 as "reconnect on the schedule". A library that doesn't pass the close code up treats every close alike, which is safe but slower to recover from a revocation.