# Protocol reference (https://sockudo.io/docs/reference/protocol)
> Compare Pusher-compatible Protocol V1 with Sockudo-native Protocol V2.
Sockudo serves two WebSocket protocols from the same server and the same port. Protocol V1 is a
byte-compatible Pusher protocol for existing clients; Protocol V2 is Sockudo's native protocol and
adds continuity metadata, recovery, rewind, filtering, and mutable messages. Use this page to look
up frame names, payload shapes, and the boundary between the two.
## Negotiating a protocol
The protocol is chosen per connection by the `protocol` query parameter on the WebSocket upgrade
URL, `GET /app/{appKey}`. Only the exact value `2` selects Protocol V2; an omitted or any other
value selects Protocol V1, so unmodified Pusher clients always land on V1.
```text
wss://realtime.example.com/app/app-key?protocol=2&format=msgpack
```
| Query parameter | Applies to | Meaning |
| --- | --- | --- |
| `protocol` | Both | `2` selects Protocol V2. Anything else, including omission, selects Protocol V1. |
| `format` | V2 | Wire format: `json` (default), `msgpack` or `messagepack`, `protobuf` or `proto`. An unknown value rejects the upgrade with `400`. V1 always uses JSON and ignores this parameter. |
| `echo_messages` | V2 | `false` stops the connection receiving its own publishes. Honored only when `[echo_control].enabled`. |
| `append_mode` | V2 | Delivery mode for mutable-message appends: `delta` (default) or `full`. An unknown value rejects the upgrade with `400`. |
| `append_rollup_window` | V2 | AI Transport append rollup window in milliseconds. Must be one of `0`, `20`, `40`, `100`, `500` and within the configured rollup bounds, otherwise the upgrade is rejected with `400`. |
| `token` | V2 | Capability-token JWT used instead of signed channel auth. |
| `client`, `version` | Both | Client library name and version, accepted for Pusher compatibility. |
See [HTTP endpoints](/docs/reference/http-endpoints#websocket) for the full upgrade contract.
## Protocol V1
Protocol V1 is Pusher-compatible. It preserves familiar event prefixes, channel names, subscription
flows, auth response shapes, and HTTP API semantics.
Use V1 for:
- existing `pusher-js` clients
- Laravel Echo migrations
- backend SDK compatibility
- minimal drop-in deployments
Typical V1 connection and event frames keep the Pusher names and payload conventions. Note that V1
`data` is a JSON-encoded string, exactly as Pusher sends it:
```json
{
"event": "pusher:connection_established",
"data": "{\"socket_id\":\"123.456\",\"activity_timeout\":120}"
}
```
```json
{
"event": "order.created",
"channel": "orders",
"data": "{\"id\":\"ord_123\",\"total\":4200}"
}
```
Keep V1 payloads compatible with existing clients. Do not require V2-only fields such as
`message_id`, `serial`, `stream_id`, tags, deltas, or annotation metadata when the recipient
negotiated V1.
## Protocol V2
Protocol V2 is Sockudo-native and uses `sockudo:` system event prefixes. Serials, message IDs, and
connection recovery are native to V2 rather than opt-in extensions.
Use V2 for:
- `message_id`
- `serial`
- `stream_id`
- connection recovery
- subscribe-time rewind
- delta compression
- tag filtering
- durable history
- mutable messages
- annotations
- push-helper client workflows through backend proxies
V2 keeps the event/channel shape familiar, then adds metadata required for continuity and durable
workflows:
```json
{
"event": "order.created",
"channel": "orders",
"data": { "id": "ord_123", "total": 4200 },
"message_id": "msg_01HX6J2P5N0Z9E",
"stream_id": "orders",
"serial": 42,
"tags": { "status": "paid", "region": "eu" },
"extras": {
"headers": { "tenant": "acme" }
}
}
```
Use V2 when the client needs to reconnect without guessing what it missed, rewind a subscription
from known history, filter by event, tags, or message content, receive deltas, or render mutable
message state.
A backend publishes once. Sockudo shapes each delivery for the subscriber's negotiated protocol:
V1 subscribers receive the Pusher frame with V2-only fields stripped, while V2 subscribers receive
the full envelope.
## System events
Every system event has one canonical name. On the wire it carries the `pusher:` or
`pusher_internal:` prefix for V1 and the `sockudo:` or `sockudo_internal:` prefix for V2. The
server accepts either prefix on inbound frames, and always replies with the prefix of the
connection's protocol.
| Canonical name | Direction | V1 | V2 | Purpose |
| --- | --- | --- | --- | --- |
| `connection_established` | Server to client | Yes | Yes | Assigns the `socket_id` and announces `activity_timeout`. |
| `error` | Server to client | Yes | Yes | Reports a protocol, auth, or limit error with a numeric `code`. |
| `ping` / `pong` | Both | Yes | Yes | Application-level heartbeat. |
| `subscribe` / `unsubscribe` | Client to server | Yes | Yes | Join or leave a channel. |
| `subscription_succeeded` | Server to client (internal) | Yes | Yes | Confirms a subscription; presence channels include the member list. |
| `subscription_error` | Server to client (internal) | Yes | Yes | Rejects a subscription. |
| `member_added` / `member_removed` | Server to client (internal) | Yes | Yes | Presence membership changes. |
| `signin` / `signin_success` | Both | Yes | Yes | User authentication. |
| `cache_miss` | Server to client | Yes | Yes | Cache channel had no cached event on subscribe. |
| `presence_update` | Both | No | Yes | Update the current member's presence data. |
| `auth` / `auth_success` | Both | No | Yes | Refresh a capability token on a live connection. |
| `token_expired` | Server to client | No | Yes | Capability token expired or was revoked. |
| `resume` / `resume_success` / `resume_failed` | Both | No | Yes | Connection recovery. |
| `rewind_complete` | Server to client | No | Yes | Subscribe-time rewind finished. |
| `channel_history` | Both | No | Yes | Read durable history over the WebSocket. |
| `message.*` | Server to client | No | Yes | Mutable message actions such as `sockudo:message.update`, `sockudo:message.delete`, and `sockudo:message.append`. |
### Connection established
Sent once, immediately after the upgrade. Store `socket_id`; backend publishes pass it as
`socket_id` to suppress echo to the originating connection.
```json
{
"event": "sockudo:connection_established",
"data": "{\"socket_id\":\"123.456\",\"activity_timeout\":120}"
}
```
### Subscribe and subscription succeeded
The client subscribes to a channel. Private and presence channels include the signed `auth`
string, and presence channels add `channel_data`. V2 subscriptions may also carry `filter`,
`rewind`, and `delta` options.
```json
{
"event": "sockudo:subscribe",
"data": {
"channel": "private-orders",
"auth": "app-key:3f2a9c..."
}
}
```
The server confirms the subscription. For presence channels, `data` carries the current
`presence` object with `ids`, `hash`, and `count`.
```json
{
"event": "sockudo_internal:subscription_succeeded",
"channel": "private-orders",
"data": "{}"
}
```
When recovery is enabled, V2 acknowledgements also include a `stream_id` and `serial`. Successful
V2 subscriptions may include `attach_serial` when durable history is enabled for the channel. See
[Protocol V2 metadata](/docs/clients/protocol-v2#v2-metadata).
### Errors
`error` frames carry a numeric `code` and a human-readable `message`, plus the `channel` when the
error relates to one. See [Error codes](/docs/reference/errors#websocket-error-and-close-codes)
for the code ranges.
```json
{
"event": "pusher:error",
"data": { "code": 4009, "message": "Connection is unauthorized" }
}
```
### Presence membership
Presence channels broadcast membership transitions. Sockudo emits `member_added` on a user's first
connection and `member_removed` on their last disconnect, not once per socket.
```json
{
"event": "sockudo_internal:member_added",
"channel": "presence-room-1",
"data": "{\"user_id\":\"user-42\",\"user_info\":{\"name\":\"Ada\"}}"
}
```
### Capability-token refresh
V2 clients that connected with `?token=` refresh before expiry by sending `sockudo:auth` with a new
token. The refreshed token must keep the same `client_id`.
```json
{ "event": "sockudo:auth", "data": { "token": "eyJhbGciOiJIUzI1NiIs..." } }
```
```json
{
"event": "sockudo:auth_success",
"data": { "client_id": "user-42", "jti": "tok_9f1c", "exp": 1710003600 }
}
```
When a token expires the server sends `token_expired` with code `40142` and reason `expired`; a
revoked token produces code `40160` and reason `revoked`.
```json
{ "event": "sockudo:token_expired", "data": { "code": 40142, "reason": "expired" } }
```
### Connection recovery
After reconnecting, a V2 client sends its last known position per channel. `channel_positions`
is the current form; the older `channel_serials` map of channel to serial is still accepted.
```json
{
"event": "sockudo:resume",
"data": {
"channel_positions": {
"orders": { "serial": 42, "stream_id": "orders", "last_message_id": "msg_01HX" }
}
}
}
```
Recoverable channels are replayed, then the server sends one aggregate `resume_success`:
```json
{
"event": "sockudo:resume_success",
"data": "{\"recovered\":[...],\"failed\":[]}"
}
```
Each channel that cannot be recovered also receives its own `resume_failed`. The `code` is one of
`position_expired`, `stream_reset`, `continuity_unverifiable`, or `persistence_unavailable`.
```json
{
"event": "sockudo:resume_failed",
"channel": "orders",
"data": "{\"code\":\"position_expired\",\"reason\":\"...\",\"expected_stream_id\":\"orders\",\"current_stream_id\":\"orders\",\"oldest_available_serial\":120,\"newest_available_serial\":180}"
}
```
`resume_failed` means Sockudo could not prove continuity. Resubscribe and rebuild state, for
example with `channel_history` and `until_attach: true`. Never advance the client cursor past a
failed position. See [History and recovery](/docs/server/history-recovery#recovery).
### Rewind complete
A V2 subscription with `rewind` (a message count, or `{ "seconds": N }`) replays recent history
before live delivery, then reports what was sent:
```json
{
"event": "sockudo:rewind_complete",
"channel": "orders",
"data": {
"historical_count": 25,
"live_count": 0,
"complete": true,
"truncated_by_retention": false,
"truncated_by_limit": false
}
}
```
### Channel history
V2 clients read durable history over the WebSocket. The response uses the same event name. See
[Client history](/docs/clients/protocol-v2#client-history) for the response fields.
```json
{
"event": "sockudo:channel_history",
"data": { "channel": "chat", "limit": 100, "direction": "backwards", "until_attach": true }
}
```
## Subscription predicates
V2 subscriptions accept one compound `filter`. Its non-empty `events`, `tags`, and `expression`
components use AND semantics; separate exact and wildcard subscriptions use OR semantics. The
expression form is either a JMESPath source string or
`{ "language": "jmespath", "source": "..." }`.
```json
{
"channel": "orders.*",
"filter": {
"events": ["order.updated"],
"tags": { "cmp": "eq", "key": "region", "val": "eu" },
"expression": "data.total >= `100` && headers.priority == `\"high\"`"
}
}
```
Predicates compile once at subscription time and apply consistently to live fanout, rewind, and
recovery. Expression projection exposes `event`, `channel`, `data`, `name`, `userId`, `tags`,
public `headers`, `messageId`, `streamId`, `serial`, and `action`. Internal `sockudo_` headers,
extras, and idempotency keys are never exposed. Source, AST, filter-tree, and projected-document
sizes are bounded; invalid input is rejected and evaluation errors fail closed. This remains gated
by Protocol V2 and `[tag_filtering].enabled`; Protocol V1 channel validation and delivery are
unchanged.
```mermaid
sequenceDiagram
participant Client
participant Sockudo
participant History
Client->>Sockudo: subscribe orders with protocol_version=2
Sockudo-->>Client: sockudo_internal:subscription_succeeded
Sockudo->>History: persist event with stream_id and serial
Sockudo-->>Client: order.created with message_id and serial
Client->>Sockudo: resume from last serial
Sockudo->>History: read gap
Sockudo-->>Client: replay missed events
```
## Prefixes
| Event family | V1 | V2 |
| --- | --- | --- |
| Public system events | `pusher:` | `sockudo:` |
| Internal events | `pusher_internal:` | `sockudo_internal:` |
| Mutable messages | not available | `sockudo:message.*` |
| Recovery | not available | `sockudo:resume_*` |
| Rewind | not available | `sockudo:rewind_complete` |
## Channel names
Channel names are limited to 200 bytes by default (configurable per app and per namespace) and may
contain ASCII letters, digits, and `- _ = @ , ; .`, plus `:` for namespaces and `#` for V2
user-limited channels. The prefix selects the channel type.
| Channel | Prefix | Auth required |
| --- | --- | --- |
| Public | none | No |
| Private | `private-` | Yes |
| Presence | `presence-` | Yes, with `channel_data` |
| Encrypted | `private-encrypted-` | Yes |
Namespaced channel rules, user-limited channel syntax, and per-namespace permissions are covered
in [Channel namespaces](/docs/reference/configuration#channel-namespaces).
## Broadcast metadata
V2 deliveries add these fields to the familiar `event`, `channel`, and `data`:
| Field | Purpose |
| --- | --- |
| `message_id` | Stable broadcast identity for deduplication. |
| `stream_id` | Opaque per-channel continuity token. Changes only when Sockudo can no longer prove continuity for the stream. |
| `serial` | Monotonically increasing per-channel position used by recovery and history. |
| `tags` | Flat string tags used by tag filtering. |
| `extras` | V2 envelope for `headers`, `ephemeral`, `echo`, `push`, and AI Transport metadata. |
```json
{
"event": "order.updated",
"channel": "orders",
"data": { "id": "ord_123" },
"message_id": "msg_01HX",
"stream_id": "orders",
"serial": 42,
"tags": { "status": "packed" },
"extras": {
"headers": { "tenant": "acme" }
}
}
```
V1 clients should not depend on V2-only fields. Idempotency keys are never sent to WebSocket
clients in either protocol.
## Compatibility boundary
The compatibility rule is simple: negotiate the richest protocol a client can safely understand,
then deliver only fields that belong to that protocol.
| Concern | V1 behavior | V2 behavior |
| --- | --- | --- |
| System prefixes | `pusher:` and `pusher_internal:` | `sockudo:` and `sockudo_internal:` |
| Event metadata | Pusher-compatible event, channel, and data | Adds serials, message IDs, stream IDs, extras, tags, and headers where enabled. |
| Recovery | Client reconnects and resubscribes | Client can resume from continuity metadata when recovery is configured. |
| Mutable messages | Not exposed | Message updates, deletes, appends, versions, and annotations are explicit V2 events. |
| Heartbeats | Pusher application `ping`/`pong` | Native WebSocket Ping/Pong, with `sockudo:ping` fallback. |
| Server publish | Pusher-shaped HTTP API | Same trusted API plus V2 acknowledgement fields when enabled. |
For mixed deployments, treat Protocol V1 as a stable contract and Protocol V2 as an opt-in
capability layer. A backend may publish once, but Sockudo must shape the delivery for each
subscriber according to the subscriber protocol.
## Push is outside the WebSocket protocol
Push notifications are HTTP-driven. They target device registrations, channel push subscriptions,
clients, or explicit recipients. A push payload may reference a realtime channel or message serial,
but provider delivery is not part of WebSocket ordering.
The optional Ably compatibility facade can resolve an Ably realtime-channel push recipient into a
native `MessageService` publish. This is an internal push target, not another network provider or
fallback transport; it follows the channel's ordinary fanout, persistence, history, version, and
idempotency semantics.
## Next steps
- [Protocol V2 for clients](/docs/clients/protocol-v2): Enable V2 in a client and handle recovery, history, and heartbeats.
- [History and recovery](/docs/server/history-recovery): How replay buffers, durable history, and rewind prove continuity.
- [HTTP endpoints](/docs/reference/http-endpoints): Publish, history, and mutable-message endpoints behind these frames.
- [Error codes](/docs/reference/errors): Interpret WebSocket error codes and HTTP failures.