WebSocket Response

Send response to a WebSocket client
Join our community

Overview

This node sends a response message to a WebSocket client connected to a specified WebSocket server. It is useful in scenarios where you want to reply or push data back to clients over WebSocket connections within an n8n workflow. For example, after processing some input data or receiving a message from a client, this node can send a confirmation, result, or any other data back to that client or broadcast it to all clients connected to the server.

Practical examples include:

  • Sending real-time updates or notifications to a specific WebSocket client.
  • Broadcasting messages to all clients connected to a WebSocket server.
  • Responding with processed data or status messages to clients after receiving their requests.

Properties

Name Meaning
Connection ID Method Where to get the WebSocket server ID from. Options: "Use Server ID from Input", "Custom Server ID", "Use Context Server".
Custom Server ID Custom WebSocket server ID to use (format: ws-{identifier}). Shown only if "Custom Server ID" method is selected.
Server ID Property Property name in the input JSON data that contains the server ID. Used if "Use Server ID from Input" is selected.
Client ID Method Where to get the client ID to send the response to. Options: "Use Client ID from Input", "Custom Client ID", "Broadcast to All Clients".
Client ID Property Property name in the input JSON data that contains the client ID. Used if "Use Client ID from Input" is selected.
Custom Client ID Custom client ID to send the response to. Shown only if "Custom Client ID" method is selected.
JSON Response Whether the response should be formatted as JSON (true) or sent as plain text (false).
Response Data The response string to send to the WebSocket client when JSON Response is false. Can contain expressions.
Response JSON The JSON object to send to the WebSocket client when JSON Response is true. Can contain expressions.

Output

The node outputs an array of JSON objects, one per input item, each containing:

  • The original input data properties.
  • success: A boolean indicating whether the message was successfully sent.
  • serverId: The ID of the WebSocket server 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 (only on failure): Error message describing why sending failed.

No binary data output is produced by this node.

Dependencies

  • Requires access to a WebSocket server managed by a shared WebSocket registry within the n8n environment.
  • Depends on a global execution context holding active WebSocket servers and their states.
  • Uses the ws WebSocket library internally for communication.
  • No external API keys or credentials are directly required by this node, but the WebSocket servers themselves may require authentication configured elsewhere.

Troubleshooting

Common Issues

  • WebSocket server not found: If the specified server ID does not correspond to an active WebSocket server, the node will throw an error.
  • Client not found on server: When targeting a specific client ID, if that client is not connected to the server, an error occurs.
  • WebSocket connection not open: If the WebSocket connection to the client is not open at the time of sending, the node retries sending up to three times before failing.
  • No active WebSocket servers in context: When using the "Use Context Server" option but no active servers exist, the node throws an error.

Error Messages and Resolutions

  • WebSocket server with ID {id} not found: Verify the server ID is correct and that the server is active.
  • Client with ID {id} not found on server {serverId}: Check that the client is connected and the client ID property matches.
  • WebSocket not open (state: {state}): Ensure the client connection is still alive before sending.
  • No active WebSocket servers found in execution context: Confirm that at least one WebSocket server is running and registered in the global context.

Links and References

Discussion