Socket Protocol

The Socket protocol is a JSON message format over a WebSocket. Prefer @qpub/sdk unless you are writing a custom client.

Connect

Authenticate on the HTTP upgrade. There is no client connect message.

GET wss://socket.qpub.io/v1?api_key=<url-encoded publicId:secret>
GET wss://socket.qpub.io/v1?access_token=<jwt>

Optional: &alias=my-client.

After the upgrade succeeds, the server sends action 1 (connected):

{
  "action": 1,
  "connection_id": "...",
  "connection_details": {
    "alias": "Alice",
    "client_id": "...",
    "server_id": "..."
  }
}

Close the socket with a normal WebSocket close. Do not send action 0 or 2 — the server rejects unsupported actions with 40002.

Client → server actions

Server → client actions

Action codes 0–3 exist in the protocol enum but are not used for normal client messaging. Prefer the table above.

Subscribe

{ "action": 4, "channel": "chat.lobby" }

Ack:

{
  "action": 5,
  "channel": "chat.lobby",
  "subscription_id": "..."
}

Publish

{
  "action": 8,
  "channel": "chat.lobby",
  "messages": [
    { "event": "chat", "data": { "text": "hi" }, "alias": "Alice" }
  ]
}

The server may reply with action 9 (published). Custom clients can ignore it; the JavaScript SDK treats publish as fire-and-forget.

Inbound message

Action 10 delivers channel data: channel, id, timestamp, and a messages array of { event, data, alias }.

Ping / pong

{ "action": 12, "id": 1 }
{ "action": 13, "id": 1 }

Errors

Error frames use action: 11 and an error object:

Short links: https://qpb.li/err{code} (for example https://qpb.li/err40300).