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

# WebSocket Commands

> Scrape live, in-play data over a long-running WebSocket connection using a WebSocket step

WebSocket is the step type for collecting live, in-play data over a long-running WebSocket connection. You add a WebSocket step to a project when you need to keep a socket open and publish data continuously as messages arrive, instead of polling an endpoint on an interval.

## When to Use WebSocket

Use a WebSocket step when:

* The source streams **live, in-play** updates over a WebSocket connection.
* You need a **persistent connection** that publishes on every update (and on a heartbeat), rather than one result per scheduled run.
* You want event-driven hooks (on connect, on message, on interval, on close) to subscribe, transform, and publish streaming data.

For request/response polling, use [HTTP Commands](/stream/commands/http).

## Adding a WebSocket Step

<Steps>
  <Step title="Add a step and set the technology">
    In your project's **Scraping flow**, add a step and set **Technology Used** to **WebSocket** (step type `WEBSOCKET`).
  </Step>

  <Step title="Add the WebSocket command">
    Add the [WebSocket](/stream/commands/ws/websocket) command as the first command in the step and set the connection **url**.
  </Step>

  <Step title="Configure the event hooks">
    Use `onConnect` to send subscription messages, `onMessage` to parse and publish each incoming message, and `onInterval` / `heartbeatIntervalMs` to keep the connection alive and re-publish on a cadence.
  </Step>

  <Step title="Publish results">
    Add [Parse](/stream/commands/parse) and [Sink](/stream/commands/sink) commands inside the hooks to transform and deliver the streamed data.
  </Step>
</Steps>

## Supported Protocols

WebSocket supports three protocol variants. Set the `protocol` parameter on the [WebSocket](/stream/commands/ws/websocket) command to select one (defaults to `native`).

| Protocol       | When to use it                                                                                  |
| -------------- | ----------------------------------------------------------------------------------------------- |
| **`native`**   | Standard WebSocket (`ws`/`wss`) feeds that push raw messages over the connection.               |
| **`signalr`**  | ASP.NET Core SignalR hubs; subscribe to hub methods via `WebSocketSignalRSettings`.             |
| **`socketio`** | Socket.IO servers; subscribe to events and set the server path via `WebSocketSocketIOSettings`. |

## Limits and Behaviors

| Behavior                    | Detail                                                                                            |
| --------------------------- | ------------------------------------------------------------------------------------------------- |
| **Live / in-play only**     | WebSocket is intended for live, in-play data streams, not one-off batch fetches.                  |
| **Item cap per step**       | Each WebSocket step processes a limited number of live items (default 500).                       |
| **Concurrent live sockets** | Up to roughly 100 live sockets run concurrently at a time.                                        |
| **Connection max lifetime** | Each live connection runs under a maximum lifetime (default 3 hours), after which it is recycled. |

### Mid-flow vs. streaming steps

* A WebSocket step that is **not the last step** in the flow opens the connection, captures an initial dump, then closes the connection. It publishes its captured result once.
* The **last step** in the flow keeps the socket open and publishes results on each heartbeat, continuously streaming live updates downstream.

See [Worked Example: Sports, Events, Event Data](/stream/commands/ws/websocket#worked-example-sports-events-event-data) for a full sports -> events -> event-data flow.

## Hooks

A WebSocket step is driven by event hooks — `onConnect`, `onMessage`, `onInterval`, `onClose`, and `onError`. For exactly when each hook fires (including the connect-then-buffer-then-process ordering) and how `heartbeatIntervalMs` re-publishes the current result, see [Hook Firing Semantics](/stream/commands/ws/websocket#hook-firing-semantics) in the WebSocket command reference — the canonical source.

## Snapshots and Deltas

Live feeds usually send an initial **snapshot** of the full state followed by incremental **deltas** carrying only what changed. A WebSocket step accumulates state across frames: your `onMessage` commands read and update values held in state, merging the snapshot and later deltas into one complete event before publishing. Because state persists for the life of the connection, the streaming step can always publish the current, fully merged event, including on a heartbeat tick when no new delta has arrived.

## Available Commands

<CardGroup cols={2}>
  <Card title="WebSocket" icon="plug-circle-bolt" href="/stream/commands/ws/websocket">
    Long-running WebSocket with full event-hook support
  </Card>

  <Card title="WebSocket Send" icon="paper-plane" href="/stream/commands/ws/websocket-send">
    Send a message over the active WS connection
  </Card>

  <Card title="WebSocket Close" icon="plug-circle-xmark" href="/stream/commands/ws/websocket-close">
    Cleanly close the active WS connection
  </Card>
</CardGroup>

## Common Use Cases

* **Live Odds Feeds**: Subscribe to in-play sports feeds and publish updates as they stream in.
* **Long-Running Connections**: Maintain connections that receive many messages over time.
* **Heartbeat Patterns**: Use `onInterval` and `heartbeatIntervalMs` to keep the connection alive and re-publish the current result.

## Related Commands

* [HTTP Commands](/stream/commands/http) - REST-based data fetching