ws component: a WebSocket client node, symmetric to the net component. Two working modes:

• Outbound dial (server=ws://host:port): acts as a WebSocket client that dials a remote server and sends messages
• Session addressing push (server=ref://<endpoint/ws instance ID>): reuses the WS connections established by the server-side endpoint to actively push to specific clients by target

TIP

• Outbound mode: text/JSON messages are sent as-is; BINARY type or messageType=binary sends binary frames
• Addressing mode: same as the net component ref:// mode, target supports ${} expressions

Configuration

Field	Type	Required	Description	Default
server	string	Yes	ws://host:port to dial and send; or ref://<endpoint/ws instance ID> for addressing push	-
target	string	No	Addressing target, only effective when server is ref://. Supports ${} expressions; sessionKey identifier (e.g. deviceId)/* (broadcast), exact match	-
headers	object	No	HTTP headers during handshake, e.g. Authorization	-
subprotocol	string	No	Sec-WebSocket-Protocol subprotocol, e.g. mqtt / ocpp1.6. Empty skips negotiation	-
connectTimeout	int	No	Dial handshake timeout (seconds), <=0 uses default	0
insecureSkipVerify	bool	No	Skip TLS certificate verification (wss:// self-signed certs)	false
messageType	string	No	Message type to send: text / binary	text
heartbeatInterval	int	No	Heartbeat interval (seconds). >0 sends periodic Ping frames for keepalive + auto-reconnect; 0=disable	60

Heartbeat & Reconnection (outbound mode)

When heartbeatInterval > 0, the outbound mode enables heartbeat keepalive and disconnect reconnection:

• Heartbeat: sends WebSocket protocol-level Ping frames at the configured interval to keep the connection alive
• Reconnection: automatically re-dials after the connection drops (Ping failure or read loop detects an error)
• Read loop: internally reads continuously to process Pong frames returned by the peer and to detect disconnections
• heartbeatInterval=0: no heartbeat and no auto-reconnect; but on write failure the connection cache is reset so the next send re-dials automatically

Concurrency safety

gorilla/websocket's WriteMessage does not support concurrent writes; the component protects business sends with an internal mutex. Ping control frames can be sent concurrently with business sends, no extra locking needed.

Relation Type

• Success: message sent/pushed successfully, forwarded to the Success chain
• Failure: the message goes to the Failure chain when:
  • dial fails (outbound mode)
  • send timeout / connection dropped
  • addressing mode: target matches no session, or the expression resolves to empty (and not explicit *)

Configuration example

Outbound dial

{
  "id": "s1",
  "type": "ws",
  "name": "Send to ws server",
  "configuration": {
    "server": "ws://127.0.0.1:8080/ws",
    "heartbeatInterval": 30
  }
}

Session addressing push (ref:// mode)

{
  "id": "s2",
  "type": "ws",
  "name": "Send command",
  "configuration": {
    "server": "ref://ws_endpoint_1",
    "target": "${metadata.deviceId}"
  }
}

With auth and subprotocol

{
  "id": "s3",
  "type": "ws",
  "configuration": {
    "server": "wss://api.example.com/stream",
    "headers": { "Authorization": "Bearer token123" },
    "subprotocol": "mqtt",
    "insecureSkipVerify": true
  }
}

Difference from endpoint/ws_client

• ws component (this one, type=ws): a sender node that dials a remote server to send, or uses ref:// to push to already-connected clients
• endpoint/ws_client: a receiver endpoint that actively connects to a remote server to subscribe to its pushed messages. See websocket client endpoint

Application example

Example reference: WebSocket client test (opens new window)