WebSocket Response

Send response to a WebSocket client

Overview

This node sends a response message to a WebSocket client connected to a specified WebSocket server. It is useful in workflows where you want to communicate back to clients over WebSocket connections, for example:

  • Sending real-time updates or notifications to a specific client.
  • Broadcasting messages to all clients connected to a WebSocket server.
  • Responding dynamically based on workflow data to individual WebSocket clients.

Practical examples include chat applications, live dashboards, multiplayer games, or any system requiring two-way communication with clients via WebSockets.

Properties

Name Meaning
Server ID ID of the WebSocket server to send the response to. Format: ws-{port} or a custom identifier.
Connection ID Method Where to get the server ID from. Options:
- Use Server ID from Input (property in input data)
- Custom Server ID (manually specify)
- Use Context Server (from active servers in execution context)
Custom Server ID Custom WebSocket server ID to use (shown if "Custom Server ID" method selected).
Server ID Property Property name in input data that contains the server ID (used if "Use Server ID from Input" method selected).
Client ID ID of the client to send the response to.
Client ID Method Where to get the client ID from. Options:
- Use Client ID from Input (property in input data)
- Custom Client ID (manually specify)
- Broadcast to All Clients (send to all clients on server)
Client ID Property Property name in input data that contains the client ID (used if "Use Client ID from Input" method selected).
Custom Client ID Custom client ID to send the response to (shown if "Custom Client ID" method selected).
JSON Response Whether the response should be formatted as JSON (true) or sent as plain text (false).
Response Data Response string to send when JSON Response is false. Can contain expressions.
Response JSON JSON data to send when JSON Response is true. Can contain expressions.

Output

The node outputs an array of JSON objects corresponding to each input item processed. Each output JSON object includes:

  • The original input data fields.
  • success: Boolean indicating if the message was successfully sent.
  • serverId: The WebSocket server ID used.
  • clientId: The client ID the message was sent to, or "broadcast" if sent to all clients.
  • serverInfo (optional): Information about the WebSocket server from the global execution context if available.
  • error (if failed): Error message describing why sending failed.

No binary data is output by this node.

Dependencies

  • Requires an active WebSocket server registered in the global execution context or identified by the provided server ID.
  • Uses a WebSocket registry singleton to manage servers and clients.
  • Depends on the ws WebSocket library internally.
  • No external API keys or credentials are required by this node itself, but the WebSocket servers must be running and accessible within the n8n environment.

Troubleshooting

  • Error: "No active WebSocket servers found in execution context"
    Occurs if "Use Context Server" is selected but no active servers exist. Ensure at least one WebSocket server is running and registered.

  • Error: "WebSocket server with ID ... not found"
    The specified server ID does not match any registered server. Verify the server ID format and that the server is active.

  • Error: "Client with ID ... not found on server ..."
    The target client ID does not exist on the specified server. Check that the client is connected and the client ID is correct.

  • Error: "WebSocket not open (state: ...)"
    The WebSocket connection to the client is not open. This may happen if the client disconnected. Retry logic is implemented but persistent failure will throw this error.

  • Message not received by client
    Confirm the client is connected to the correct server and listening for messages. Also verify the message format matches client expectations (JSON vs plain text).

  • Retries and delays
    The node attempts up to 3 retries with 500ms delay between tries when sending messages fails due to connection issues.

Links and References

Discussion