node-red-contrib-whatsapp-bridge

Node-RED nodes for WhatsApp via whatsapp-web.js or @whiskeysockets/baileys.

This is a fork of [email protected] by Ravi Mishra, with bug fixes and modernization. It is a drop-in replacement — the same six Node-RED node types (whatsappLink, chats-in, chats-out, group-out, admin, reply) are registered, the same session-storage paths are used, and existing flow JSON loads without edits.

Why

The upstream package works for happy-path phone-number recipients but fails or behaves badly in several real scenarios — silent send failures for @lid recipients, double-sending of button payloads, crashes on message.key.remoteJid, swallowed status timers, a typo that broke the destroy admin command, and more. This fork fixes them while staying compatible with existing flows. See CHANGES.md for the full list (16 documented bugs, all fixed).

Install

For an existing Node-RED whatsapp-link user, see MIGRATION.md.

For a fresh install:

cd ~/.node-red
npm install node-red-contrib-whatsapp-bridge

Nodes

| Node | Purpose | | -------------- | ----------------------------------------------------------------- | | whatsappLink | Config node holding the underlying WhatsApp client | | chats-in | Inbound message events | | chats-out | Outbound message sender (text, image, buttons) | | group-out | Outbound to a configured group JID | | admin | destroy / logout / restart / test admin commands | | reply | Auto-reply or react when an incoming message starts with a prefix |

The Baileys backend (waSocketClient) supports buttons, lists, and template messages. The whatsapp-web.js backend (waWebClient) supports text and images and renders the QR code in the Node-RED admin node.

Inputs of interest

chats-out / group-out:

| Field | Description | | -------------- | ---------------------------------------------------------------- | | msg.payload | Text body, or a buttons/list/template object (Baileys) | | msg.image | Base64 image; msg.payload becomes the caption | | msg.toNumber | Recipient — phone number, full JID, or array of either | | msg.key | Pass message.key from a chats-in event to reply to that chat |

Recipient strings containing @ are passed through unchanged. Both backends accept @lid, @c.us, @g.us, @s.whatsapp.net, and @newsletter.

chats-in emits:

| Field | Description | | ------------------- | ------------------------------------------------------------------- | | msg.payload | Message body | | msg.from | Sender, digit-stripped (legacy — still emitted) | | msg.chatID | Chat, digit-stripped (legacy — still emitted) | | msg.sourceJid | Sender, full JID including suffix — persist this to reply later | | msg.sourceChatJid | Chat, full JID | | msg.message | The original whatsapp-web.js Message or Baileys envelope | | msg.reaction | {emoji, targetKey} for reaction messages (v1.4) | | msg.mediaInfo | {kind, mimetype, filename, fileLength} for media messages (v1.4) |

Actions (v1.4)

Beyond text/image sends, chats-out / group-out recognise these msg shapes and dispatch the corresponding backend call:

| Field | Effect | | -------------------- | ----------------------------------------------------------------------------------------------- | | msg.markRead | Send read receipts. Pass a message.key (from chats-in) or array of keys. | | msg.presence | 'composing' / 'recording' / 'paused' / 'available' / 'unavailable'. Recipient resolved from msg.toNumber / msg.key / the node default. Baileys 'available'/'unavailable' are global. | | msg.react | {emoji, key} — react to a message. emoji: '' clears. Web backend additionally needs msg.message. | | msg.poll | {name, values, selectableCount?}. Baileys only. | | msg.downloadMedia | true (uses the carried envelope) or an explicit envelope. Result is attached as msg.media = {mimetype, data:Buffer, filename?}. |

Action messages flow through the same retry + sequential queue as regular sends. They can be combined: a single msg with both markRead and react runs them in order.

Tuning

The send queue and retry behaviour read from environment variables at load time. Set them where Node-RED is launched (e.g. environment: in docker-compose.yml). Defaults match the v1.0 behaviour with the addition of per-recipient pacing.

| Variable | Default | What it controls | |-----------------------------------|---------|-----------------------------------------------------------------------------------------------| | WA_BRIDGE_PER_RECIPIENT_GAP_MS | 1500 | Minimum gap between consecutive sends to the same JID. Different recipients run back-to-back. | | WA_BRIDGE_MAX_QUEUE_DEPTH | 1000 | Max pending sends per outbound node before further inputs are dropped with node.error. | | WA_BRIDGE_RETRY_ATTEMPTS | 3 | Total attempts for transient send errors (connection-closed, 408, 503, 410/428/515). | | WA_BRIDGE_RETRY_BACKOFF_MS | 500 | Initial backoff; doubles per attempt (500 → 1000 → 2000). |

Development

npm install
npm test            # 86 tests (78 unit + 5 smoke + 3 isRetryable)

Smoke tests use node-red-node-test-helper and require Node-RED itself; both are devDependencies. Unit tests use only node:test and run without any install.

License

ISC. See LICENSE. Original work © Ravi Mishra; fork modifications © M.Alsouki