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.
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.
api.dev.wbskt.com{ type, payload }| Gateway | Status | Good for |
|---|---|---|
| WebSocketwss://ws.dev.wbskt.com/ws | Available | Boards that stay connected. Every SDK uses it. |
| MQTTmqtts://mqtt.dev.wbskt.com:8883 | Available | Boards and firmware that already speak MQTT. Any MQTT library works, with no WBSKT library needed. |
| Others, like plain HTTPS | Not planned yet | Any 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.
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 }
| status | Means |
|---|---|
| 1 Registered | The policy approves on its own. Log in now. |
| 0 Pending | Someone 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.
| Answer | Do |
|---|---|
| 200 | Connect. |
401CLIENT_NOT_REGISTERED | Pending approval, revoked or rejected. Retry on the reconnect schedule. |
401CLIENT_UNAUTHORIZED | Credentials no longer valid. Clear them and register again. |
| 429 | Rate 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.
{ "type": "temperature", "payload": { "celsius": 21.5 }, "sentAt": "2026-10-31T12:00:00Z" }| Field | Direction | Notes |
|---|---|---|
type | both | 1–100 characters, compared ignoring case. |
payload | both | Any JSON value. The whole message is at most 64 KB. |
sentAt | client → server | When it was made. More than 30 s old on arrival means late. |
commandId | server → client | On a command that wants confirming. |
expiresAt | server → client | Don't act on the command after this. |
Reserved types
| Type | Direction | What to do |
|---|---|---|
capabilities | client → server | Send first on every connection: agent, version, the commands you take, firmware version. |
state.report | client → server | The state variables that changed. Numbers are kept for charts. |
sys.ping / sys.pong | both | Answer each ping at once, echoing its id and timestamp. |
sys.ack | client → server | Confirm a command on arrival, or refuse it with refused: "expired". |
sys.ota.update / sys.ota.status | both | Optional 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.
| Reason | Do |
|---|---|
| Normal | Reconnect on the schedule. |
| Restarting | Reconnect after a random 0–30 s. |
| Too big | A message was over 64 KB. Fix the sender. |
| Server error | Reconnect on the schedule. |
| Superseded | The same client connected again. Repeated, it means two boards share credentials. |
| Revoked | Drop the token; the next login says what happened. |
| Throttled | Wait a random 30–60 s and send less. |
| Updating from client | A 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.
| Situation | Wait |
|---|---|
| Connection just dropped | random 0–10 s |
| Server is restarting | random 0–30 s |
| n-th failure in a row | random 0–min(60 s, 2 s × 2ⁿ) |
| Answered 429 | Retry-After + random 0–2 s |