Node-RED integration

@open-wa/node-red connects Node-RED to an already running open-wa Easy API instance. The current package is 5.1.0 and registers exactly three node types: the owa-server configuration node, Command, and Listen. It does not provide separate Send, Receive, Session, or Media nodes.

PrerequisitesCopy Anchor Link

• Node-RED 5.x and Node.js available on the machine that runs the flow.
• An authenticated open-wa session with Easy API enabled.
• The Easy API base URL, for example http://127.0.0.1:8080.
• The Easy API key if the session was started with --api-key.

Install the supported packageCopy Anchor Link

Install into the Node-RED user directory so Node-RED can load it from its palette:

cd ~/.node-red
npm install @open-wa/node-red@5.1.0
node-red

Open http://127.0.0.1:1880, choose Manage palette, and confirm the @open-wa/node-red package is installed. The package name is @open-wa/node-red; the older @open-wa/node-red-contrib-wa-automate guide describes a different package and palette.

Connect to Easy APICopy Anchor Link

Start an Easy API session separately. This loopback example requires Node-RED and Easy API to run on the same machine. Replace the API-key placeholder with a local secret before running it; for remote access, follow the network and security guidance and use an API address reachable from the Node-RED host.

export OPENWA_API_KEY="replace-with-your-api-key"
npx @open-wa/wa-automate@5.1.0 --session-id sales --host 127.0.0.1 --port 8080 --api-key "$OPENWA_API_KEY"

In Node-RED, add the owa-server configuration node and fill these fields:

The node creates a SocketClient for that URL. In v5 the client uses HTTP RPC for commands and the event stream for listeners; the old node help text mentioning --socket is stale for this package.

Current paletteCopy Anchor Link

owa-server configuration nodeCopy Anchor Link

Stores name, url, and optional key. It reports connected, disconnected, and connection-error status and keeps the client available to the flow.

CommandCopy Anchor Link

The visible palette label is Command and the runtime type is cmd. It loads command names from /meta/basic/commands, then calls the selected method through the configured server. Set method and JSON args in the node, or provide msg.method and msg.args at runtime. A command waits for the server connection and defaults to a 30-second timeout; set timeout to -1 only when an unbounded call is intentional.

For sendText, the argument object is:

{
  "to": "1234567890@c.us",
  "content": "Hello from Node-RED"
}

ListenCopy Anchor Link

The visible palette label is Listen and the runtime type is listen. It loads listener names from /meta/basic/listeners, registers one listener against the server, and emits received data as msg.payload. Use onMessage for inbound message events; the listener is stopped when the node closes.

Importable echo flowCopy Anchor Link

Import this JSON from Node-RED's menu (Import → Clipboard). Edit the url and key on the owa-server configuration node before deploying. The flow listens for onMessage and sends pong only when an inbound text message is exactly ping, ignoring letter case and surrounding spaces. It sends a WhatsApp reply, so deploy it only when you intend to reply to matching messages.

[
  {
    "id": "openwa-tab",
    "type": "tab",
    "label": "open-wa echo",
    "disabled": false,
    "info": "Echo inbound messages through the v5 Easy API client"
  },
  {
    "id": "openwa-server",
    "type": "owa-server",
    "name": "sales Easy API",
    "url": "http://127.0.0.1:8080",
    "key": "REPLACE_WITH_API_KEY"
  },
  {
    "id": "openwa-listen",
    "type": "listen",
    "z": "openwa-tab",
    "name": "incoming messages",
    "server": "openwa-server",
    "listener": "onMessage",
    "x": 170,
    "y": 120,
    "wires": [["openwa-format"]]
  },
  {
    "id": "openwa-format",
    "type": "function",
    "z": "openwa-tab",
    "name": "make echo command",
    "func": "const message = msg.payload || {};\nif (!message.from || typeof message.body !== 'string' || message.body.trim().toLowerCase() !== 'ping') return null;\nmsg.method = 'sendText';\nmsg.args = { to: message.from, content: 'pong' };\nreturn msg;",
    "outputs": 1,
    "x": 390,
    "y": 120,
    "wires": [["openwa-command"]]
  },
  {
    "id": "openwa-command",
    "type": "cmd",
    "z": "openwa-tab",
    "name": "sendText",
    "server": "openwa-server",
    "method": "sendText",
    "args": "{}",
    "timeout": "30",
    "x": 610,
    "y": 120,
    "wires": [["openwa-debug"]]
  },
  {
    "id": "openwa-debug",
    "type": "debug",
    "z": "openwa-tab",
    "name": "send result",
    "active": true,
    "tosidebar": true,
    "complete": "payload",
    "x": 820,
    "y": 120,
    "wires": []
  }
]

The REPLACE_WITH_API_KEY value is a placeholder, not a secret to commit. This node stores key as an ordinary flow property, not as a declared Node-RED credential. Do not commit or share an exported flow containing a real key, and restrict access to the Node-RED editor and flow exports. Confirm that the owa-server URL and key match the running Easy API.

TroubleshootingCopy Anchor Link

For the canonical readiness and authentication checks, see Readiness and authentication checks.

RelatedCopy Anchor Link

• Easy API quick start
• Socket Client
• Webhooks for Business