Skip to main content

websocket-out

Send messages over WebSocket connections to clients or servers.

websocket-out
output v1.0.0

Send messages over WebSocket connections. Broadcast to all connected clients or send to a specific client.

websocket realtime streaming push
Inputs
1
Outputs
0

Overview

The websocket-out node sends messages over WebSocket connections. Use it to:

  • Push updates - Send real-time data to dashboard clients
  • Broadcast alerts - Notify all connected users instantly
  • Reply to clients - Respond to specific client requests
  • Stream data - Continuous sensor data to visualizations

This node pairs with websocket-in. Configure them with the same path to create bidirectional communication channels.

Properties

Property Type Required Default Description
name string - - Display name for this node in the editor.
mode string server Connection mode: "server" (send to connected clients) or "client" (send to server).
path string /ws WebSocket path for server mode, or full URL for client mode.
wholemsg boolean - false If true, sends the entire msg object as JSON. If false, sends only msg.payload.

Inputs

Control message delivery using these properties:

Property Type Description
msg.payload any Content to send (auto-stringified if object)
msg._session object Target specific client (from websocket-in)

Broadcast vs Unicast

Broadcast Send to All Clients

When msg._session is not set, the message is sent to all connected clients on that WebSocket path. 

// Broadcast to everyone
msg.payload = { alert: "System maintenance in 5 minutes" };
return msg; // No _session = broadcast
Unicast Send to Specific Client

When msg._session is set (preserved from websocket-in), the message is sent only to that client. 

// Reply to specific client
// msg._session is preserved from websocket-in
msg.payload = { response: "Request processed" };
return msg; // Sent only to original sender
Tip: Managing Sessions

Store _session objects in flow context to send messages to specific clients later, even from different flows.

Examples

Broadcast Sensor Updates

Push sensor data to all connected dashboard clients.

Live Sensor Broadcast

Broadcasts temperature readings to all connected WebSocket clients.

View Flow JSON 
[
  {
    "id": "sensor1",
    "type": "dht22",
    "name": "DHT22",
    "pin": 4,
    "wires": [["function1"]]
  },
  {
    "id": "function1",
    "type": "function",
    "name": "Format Data",
    "func": "msg.payload = {\n  type: 'sensor_update',\n  temperature: msg.payload.temperature,\n  humidity: msg.payload.humidity,\n  timestamp: Date.now()\n};\nreturn msg;",
    "wires": [["wsout1"]]
  },
  {
    "id": "wsout1",
    "type": "websocket-out",
    "name": "Broadcast",
    "mode": "server",
    "path": "/ws/sensors"
  }
]

Reply to Client Request

Receive a query and reply only to the requesting client.

Request/Response

Handles client queries and sends responses back to the requester.

View Flow JSON 
[
  {
    "id": "wsin1",
    "type": "websocket-in",
    "name": "Requests",
    "mode": "server",
    "path": "/ws/api",
    "wires": [["function2"]]
  },
  {
    "id": "function2",
    "type": "function",
    "name": "Process Query",
    "func": "// _session is automatically included\nconst query = JSON.parse(msg.payload);\n\nif (query.action === 'get_status') {\n  msg.payload = {\n    status: 'online',\n    uptime: process.uptime(),\n    memory: process.memoryUsage().heapUsed\n  };\n}\n// _session is preserved, so reply goes to this client only\nreturn msg;",
    "wires": [["wsout2"]]
  },
  {
    "id": "wsout2",
    "type": "websocket-out",
    "name": "Reply",
    "mode": "server",
    "path": "/ws/api"
  }
]

Real-time Dashboard

Complete WebSocket dashboard with multiple data streams.

Dashboard Hub

Aggregates data from multiple sources and pushes to dashboard clients.

View Flow JSON 
[
  {
    "id": "mqtt1",
    "type": "mqtt-in",
    "name": "Sensors",
    "topic": "sensors/#",
    "wires": [["function3"]]
  },
  {
    "id": "function3",
    "type": "function",
    "name": "Format",
    "func": "const topic = msg.topic.split('/');\nmsg.payload = {\n  type: 'mqtt',\n  source: topic[1],\n  metric: topic[2],\n  value: msg.payload,\n  timestamp: Date.now()\n};\nreturn msg;",
    "wires": [["wsout3"]]
  },
  {
    "id": "inject1",
    "type": "inject",
    "name": "System Stats",
    "repeat": "5",
    "wires": [["function4"]]
  },
  {
    "id": "function4",
    "type": "function",
    "name": "Get Stats",
    "func": "msg.payload = {\n  type: 'system',\n  cpu: os.loadavg()[0],\n  memory: os.freemem() / os.totalmem() * 100,\n  timestamp: Date.now()\n};\nreturn msg;",
    "wires": [["wsout3"]]
  },
  {
    "id": "wsout3",
    "type": "websocket-out",
    "name": "Dashboard",
    "mode": "server",
    "path": "/ws/dashboard"
  }
]

Troubleshooting

Messages not reaching clients
  • Verify clients are connected (check websocket-in for connect events)
  • Ensure the path matches between in and out nodes
  • Check if msg._session is unexpectedly set (causing unicast instead of broadcast)
  • Add a debug node before websocket-out to verify messages are flowing
Client receives [object Object]

Objects are automatically JSON-stringified. If you're seeing [object Object], make sure you're parsing the message on the client side:

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data);
}
Reply going to all clients instead of one

The _session object may have been lost or removed:

  • Make sure you're not replacing the entire msg object
  • Use msg.payload = ... instead of msg = {...}
  • If storing for later, save the full _session object
Binary data not sending correctly

Send binary data as a Buffer:

msg.payload = Buffer.from(binaryData);
return msg;

On the client, handle as ArrayBuffer or Blob depending on your needs.

Related Nodes

websocket-in input

Receive WebSocket messages.
http-in input

HTTP request/response endpoints.
mqtt-out output

Publish to MQTT topics.