DocsReferenceClient protocolOverview

Client protocol

How any client talks to WBSKT, whatever language it's written in and whatever carries its messages. The SDKs follow this page, and a client written from scratch against it is just as supported.

Version v1Gateways WebSocket, MQTTUpdated 9 Nov 2026

How it fits together

A client deals with three layers. Only the middle one depends on how the board is connected, so the same messages work over any gateway.

1HTTPS APIRegister once, then log in for a token. The same for every client.api.dev.wbskt.com
2GatewayHolds the connection and carries messages both ways. Each transport has its own gateway.WebSocketMQTT
3MessagesReadings, commands, acks, state and pings. The same JSON whatever the gateway.{ type, payload }
GatewayStatusGood for
WebSocketwss://ws.dev.wbskt.com/wsAvailableBoards that stay connected. Every SDK uses it.
MQTTmqtts://mqtt.dev.wbskt.com:8883AvailableBoards and firmware that already speak MQTT. Any MQTT library works, with no WBSKT library needed.
Others, like plain HTTPSNot planned yetAny transport can be added as a gateway without changing the messages. Ask for one.

Whichever gateway a client uses, the rules on this page apply: one connection per client (connecting again ends the older one), capabilities first on every connection, and the same limits.

At a glance

Two HTTPS calls, then one connection through a gateway, held open.

Once, over HTTPS
01 to WBSKTPOST /client-registrations/initiatewith the PIN and a name
02 to client{ clientRefId, secret, status }keep these for good
Whenever it needs a token
03 to WBSKTPOST /client-auth/login
04 to client{ accessToken, expiresIn }reuse until it nearly expires
Then one connection through a gateway, held open
05 to WBSKTconnect with the tokenover WebSocket: GET /ws. Over MQTT: CONNECT
06 to WBSKTcapabilitiesalways first
07 to clientsys.pingevery few seconds
08 to WBSKTsys.ponganswer each ping at once
09 to WBSKTtemperature { celsius: 21.5 }your readings
10 to clientrelay.set + commandIda command
11 to WBSKTsys.ack { commandId }on arrival

1. Register, once

Send a policy's PIN and a name. Store the answer for good (a file, or NVS on a microcontroller) and never register again while you have it: each registration is a new client and counts against the policy's limit.

POST /api/v1/client-registrations/initiate

{ "pin": "483920", "name": "greenhouse-sensor" }
200 OK

{
  "clientRefId": "6f1c2a9e-4d3b-4c1a-9a57-2e0b8f3d7c10",
  "secret": "k3Jx…",
  "status": 1
}
statusMeans
1  RegisteredThe policy approves on its own. Log in now.
0  PendingSomeone has to approve it in the console. Login answers CLIENT_NOT_REGISTERED until then; keep retrying.

2. Log in

Trade the credentials for an access token. Reuse the token on every reconnect until a minute before expiresIn runs out.

AnswerDo
200Connect.
401CLIENT_NOT_REGISTEREDPending approval, revoked or rejected. Retry on the reconnect schedule.
401CLIENT_UNAUTHORIZEDCredentials no longer valid. Clear them and register again.
429Rate limited. Wait Retry-After plus up to 2 s.

3. Messages

Every message, both ways, is a JSON object with a type and a payload.

message.json
{ "type": "temperature", "payload": { "celsius": 21.5 }, "sentAt": "2026-10-31T12:00:00Z" }
FieldDirectionNotes
typeboth1–100 characters, compared ignoring case.
payloadbothAny JSON value. The whole message is at most 64 KB.
sentAtclient → serverWhen it was made. More than 30 s old on arrival means late.
commandIdserver → clientOn a command that wants confirming.
expiresAtserver → clientDon't act on the command after this.

Reserved types

TypeDirectionWhat to do
capabilitiesclient → serverSend first on every connection: agent, version, the commands you take, firmware version.
state.reportclient → serverThe state variables that changed. Numbers are kept for charts.
sys.ping / sys.pongbothAnswer each ping at once, echoing its id and timestamp.
sys.ackclient → serverConfirm a command on arrival, or refuse it with refused: "expired".
sys.ota.update / sys.ota.statusbothOptional firmware updates. The ESP32 library handles them for you.

4. Limits and pacing

  • Send at most 8 messages a second after a burst of 50, a flushed offline backlog included.
  • The gateway drops anything past 10 a second (burst 100) and closes the connection after 500 drops in a row.
  • Commands wait up to 24 hours for an offline client and arrive oldest first.

5. When a connection ends

WBSKT always says why it ended a connection. Each gateway signals it its own way: on the WebSocket gateway it's the close code, and on the MQTT gateway the DISCONNECT reason code.

ReasonDo
NormalReconnect on the schedule.
RestartingReconnect after a random 0–30 s.
Too bigA message was over 64 KB. Fix the sender.
Server errorReconnect on the schedule.
SupersededThe same client connected again. Repeated, it means two boards share credentials.
RevokedDrop the token; the next login says what happened.
ThrottledWait a random 30–60 s and send less.
Updating from clientA client closing to install firmware. Shown as updating, not offline, for 5 minutes.

6. Reconnecting

Always wait a random time between zero and a ceiling, so a fleet doesn't reconnect at the same instant. The SDKs do all of this for you.

SituationWait
Connection just droppedrandom 0–10 s
Server is restartingrandom 0–30 s
n-th failure in a rowrandom 0–min(60 s, 2 s × 2ⁿ)
Answered 429Retry-After + random 0–2 s