@open-wa/node-red
Official @open-wa node-red integration.
@open-wa/node-redSource:
integrations/node-red/README.md
@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/wa-automate@5.1.0 \
--session-id sales \
--port 8080 \
--api-key "$OPENWA_API_KEY"
cd ~/.node-red
npm install @open-wa/node-red@5.1.0
node-redOpen 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 ashttp://127.0.0.1:8080.key: Optional API key. The editor sends it asX-API-Keywhile loading command and listener metadata, and the client uses it for runtime requests.
cmd
server: The owa-server configuration node.method: Command name, such assendText.args: JSON arguments. Message values inmsg.methodandmsg.argstake precedence; object-likemsg.payloadis merged when configured arguments are object-like.timeout: Seconds. Invalid or empty values fall back to 30 seconds;-1intentionally disables the command timeout.
For sendText, the command arguments can be an object:
{
"to": "1234567890@c.us",
"content": "Hello from Node-RED"
}listen
server: The owa-server configuration node.listener: Listener name, for exampleonMessage.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/commandsA 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 devThe 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.
Was this helpful?
Your answer includes the page path and docs version.