WebSocket
Keep a WebSocket open to an allowlisted host, sending and receiving messages with optional reconnect.
- Web
- Since 0.2.0
- web
- websocket
- socket
- stream
- realtime
- network
- data
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#
| 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 |
Parameters#
| 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. |
url: url.protocols: strings.
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 through Convert.
- During replay the socket stays closed and the recorded messages are played back.
See also#
Web request, Console log, Convert, Data cables.
Help patches
Each help patch is an ordinary Toy that teaches one idea. The diagram shows the Patch; the preview shows its Frame. Open it in TuneToys to play and edit it.
1. An echo socket
intermediate Teaches: parse, reconnect, heartbeat
A WebSocket to a public echo server: Value sends a greeting and the reply is logged.
Connections as text
- Value value output connected to WebSocket send input
- WebSocket message output connected to Console log “log” value input
- WebSocket state output connected to Console log “state” value input
- Parse Text keeps replies as strings; JSON would parse them.
- Reconnect Backoff retries after a drop, waiting longer each time.
Related nodes
- Web request Fetch a URL on each trigger under the network allowlist; secrets come from a vault slot, never the Toy.
- Console log Write each incoming value to the Console panel with a level and label, rate-limited.
- Convert Convert a value to another datatype, optionally picking a field or formatting a string; failures go to error.