# WebSocket

> Keep a WebSocket open to an allowlisted host, sending and receiving messages with optional reconnect.

Source: https://docs.tune.toys/nodes/web.socket/

WebSocket keeps a live two-way connection to a server: anything cabled into `send` goes out, every message that comes back arrives on `message`.

## What it does

The node connects when the Toy starts, or on each `connect` trigger when that input is cabled; `close` closes it. The URL is the node's `url` field, `wss:` only (`ws:` only for localhost), and its host must be in your network allowlist. The browser connects directly; WebSockets do not pass through the proxy and never carry your keys. `state` reports `connecting`, `open`, `reconnecting` and `closed`; `error` explains failures.

Messages you send are written as text (objects as JSON). Incoming messages are parsed per Parse.

## When to use it

Use it for live feeds and for talking to your own server or tools on your computer, such as a local bridge at `ws://localhost`.

## Ports

<!-- ports:start -->

| Port      | Direction | Signal         | Lanes |
| --------- | --------- | -------------- | ----- |
| `send`    | Input     | Data (any)     | 1     |
| `connect` | Input     | Data (trigger) | 1     |
| `close`   | Input     | Data (trigger) | 1     |
| `message` | Output    | Data (any)     | 1     |
| `state`   | Output    | Data (string)  | 1     |
| `error`   | Output    | Data (string)  | 1     |

<!-- ports:end -->

## Parameters

<!-- parameters:start -->

| Parameter   | Label     | Range    | Default | Unit | Scale  | Notes                                                                       |
| ----------- | --------- | -------- | ------- | ---- | ------ | --------------------------------------------------------------------------- |
| `parse`     | Parse     | 0 to 3   | 0       |      | linear | How incoming messages are read. Choices: 0 JSON, 1 Text, 2 Bytes, 3 Auto.   |
| `reconnect` | Reconnect | 0 to 1   | 1       |      | linear | Reconnect with exponential backoff after a drop. Choices: 0 Off, 1 Backoff. |
| `heartbeat` | Heartbeat | 0 to 300 | 0       | s    | linear | Seconds between keep-alive pings; 0 sends none.                             |

<!-- parameters:end -->

<!-- data:start -->

- `url`: url.
- `protocols`: strings.

<!-- data:end -->

### Parse (`parse`)

JSON, Text, Bytes or Auto. It sets the datatype of `message`.

### Reconnect (`reconnect`)

Off, or Backoff: after a drop, reconnect after 0.5 seconds, doubling the wait each time up to 30 seconds, and reset after a successful open.

### Heartbeat (`heartbeat`)

A liveness timeout in seconds; 0 turns it off. If no message arrives for that long the socket is closed (and reopened with Backoff). The node sends no ping frames of its own.

### URL and protocols

The `url` field is the socket address; the `protocols` field lists up to eight subprotocols to offer.

## Tips

- Many services need a subscription message after connecting; send it from a [Value](https://docs.tune.toys/nodes/data.value/) through [Convert](https://docs.tune.toys/nodes/data.convert/).
- During [replay](https://docs.tune.toys/concepts/takes/) the socket stays closed and the recorded messages are played back.

## See also

[Web request](https://docs.tune.toys/nodes/web.request/), [Console log](https://docs.tune.toys/nodes/log.console/), [Convert](https://docs.tune.toys/nodes/data.convert/), [Data cables](https://docs.tune.toys/concepts/data-cables/).