> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sportrix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSocket Message Reference — Sportrix Data Stream

> Complete reference for Sportrix Data WebSocket client messages (subscribe, unsubscribe) and server frames (snapshot, update, error).

This page documents every message you can send to the Sportrix Data WebSocket stream and every frame the server can send back. For connection setup and a quick-start example, see the [WebSocket overview](/api/websocket-overview).

## Client → Server messages

Send JSON objects to subscribe or unsubscribe from a match. The `match_id` is the integer id returned by the REST `/matches` endpoints.

**Subscribe:**

```json theme={null}
{"action": "subscribe", "match_id": 41282}
```

**Unsubscribe:**

```json theme={null}
{"action": "unsubscribe", "match_id": 41282}
```

### Control message fields

| Field      | Type    | Description                                                       |
| ---------- | ------- | ----------------------------------------------------------------- |
| `action`   | string  | `"subscribe"` to start receiving updates, `"unsubscribe"` to stop |
| `match_id` | integer | The match id to subscribe to or unsubscribe from                  |

## Server → Client frames

Every frame the server sends is a JSON object with an `op` field that identifies the frame type.

| `op`       | When sent                                             | Additional fields                     |
| ---------- | ----------------------------------------------------- | ------------------------------------- |
| `snapshot` | Immediately after a successful subscribe              | `data`: full live snapshot object     |
| `update`   | Whenever a subscribed match state changes             | `data`: full live snapshot object     |
| `error`    | On a bad control message or unauthorized subscription | `error`: human-readable reason string |

The `data` object is a complete [live snapshot](/api/live-snapshot), and always includes a `match_id` field. This lets a single connection multiplex updates from many matches — inspect `data.match_id` to route each frame to the right handler.

<Note>
  The snapshot schema **depends on the sport** — branch on `data.sport` before reading sport-specific fields. Soccer carries `clock`/`phase`/`stats`/`events`; cricket carries `score`/`over`/`batsmen`/`bowler`/`scorecard`. See the [live snapshot reference](/api/live-snapshot) for both shapes.
</Note>

### Example frames

```json theme={null}
{"op": "snapshot", "data": {"match_id": 41282, "status": "live", "score": {"home": 3, "away": 2}}}
{"op": "update", "data": {"match_id": 41282, "status": "live", "score": {"home": 3, "away": 3}}}
{"op": "error", "error": "match not live or not found"}
```

<Note>
  v1 sends a **full snapshot** on every `update` frame — there are no field-level deltas. Your handler can replace its local state entirely on each frame.
</Note>

<Note>
  Subscribing to a match outside your enabled sport allowlist returns an `error` frame. The error message will indicate that the sport is not enabled for your API key.
</Note>