@open-wa/node-red

@open-wa/node-red connects Node-RED flows to an existing open-wa Easy API session. The current package is 5.1.0 and registers three node types: owa-server, cmd, and listen.

The integration keeps the Node-RED palette small and maps commands and events to the Easy API metadata endpoints. It uses @open-wa/socket-client as the compatibility client; v5 commands travel over HTTP RPC and runtime events use the client event stream.

Quick start

Start Easy API separately, then install the package into Node-RED's user directory:

npx @open-wa/[email protected] \
  --session-id sales \
  --port 8080 \
  --api-key "$OPENWA_API_KEY"

cd ~/.node-red
npm install @open-wa/[email protected]
node-red

Open http://127.0.0.1:1880, choose Manage palette, and confirm @open-wa/node-red is installed. Add an owa-server configuration node with the Easy API URL and the same key passed to --api-key. Leave the key empty only when Easy API was started without one.

The configuration node keeps the SocketClient in Node-RED global context. It reports connected, disconnected, and connection-error states so a flow can distinguish a stopped API from a command failure.

Node types

| Palette label | Runtime type | Behavior | | --- | --- | --- | | owa-server | owa-server | Stores name, url, and optional key, creates a SocketClient, and owns the connection lifecycle. | | Command | cmd | Loads command metadata from /meta/basic/commands, then calls client.ask(method, args) with node or message values. | | Listen | listen | Loads listener names from /meta/basic/listeners, subscribes with client.listen(listener, callback), and emits event data as msg.payload. |

The visible labels are Command and Listen. Older guides that describe separate Send, Receive, Session, or Media nodes refer to @open-wa/node-red-contrib-wa-automate, which is a different package and palette.

Configuration fields

owa-server

• name: Node-RED display name.
• url: Easy API base URL, such as http://127.0.0.1:8080.
• key: Optional API key. The editor sends it as X-API-Key while loading command and listener metadata, and the client uses it for runtime requests.

cmd

• server: The owa-server configuration node.
• method: Command name, such as sendText.
• args: JSON arguments. Message values in msg.method and msg.args take precedence; object-like msg.payload is merged when configured arguments are object-like.
• timeout: Seconds. Invalid or empty values fall back to 30 seconds; -1 intentionally disables the command timeout.

For sendText, the command arguments can be an object:

{
  "to": "[email protected]",
  "content": "Hello from Node-RED"
}

listen

• server: The owa-server configuration node.
• listener: Listener name, for example onMessage.
• name: Node-RED display name.

The listener stops when its node closes or its server disconnects. A session that is not authenticated or ready cannot emit WhatsApp events even when Node-RED itself is running.

Connection checks

Use the same URL and key outside Node-RED to separate API reachability, authentication, and session readiness:

curl -sS -D - \
  -H "X-API-Key: $OPENWA_API_KEY" \
  http://127.0.0.1:8080/health

curl -sS -D - \
  -H "X-API-Key: $OPENWA_API_KEY" \
  http://127.0.0.1:8080/meta/basic/commands

A connection refusal means the URL or process is wrong. 401 means the configured key is absent or different. A 200 health response with connected: false or session.ready: false means Node-RED can reach Easy API but the WhatsApp session still needs authentication or readiness work.

Development

From the monorepo checkout:

pnpm --filter @open-wa/node-red dev

The package source lives under integrations/node-red; the published Node-RED entrypoints are the dist/nodes/* files declared in package.json.

Documentation

See the Node-RED guide for the importable echo flow and the full troubleshooting journey.

License

H-DNH 1.1. The MIT notice is retained for upstream Node-RED code.