node-red-contrib-notification-collection

A collection of Node-RED nodes for sending notifications across multiple channels.

The package is designed around a consistent notification pattern (templating, queueing, delivery), with WhatsApp as the first available channel. Additional channels such as email and SMS are planned.

Concept

This structure applies to all channels. Currently, only WhatsApp nodes are available.

Each channel follows the same structure:

• A config node manages the connection and credentials
• An out node renders a template and delivers the message
• An in node receives incoming messages and emits them into the flow

All channels share the same principles:

• Nunjucks templating with msg properties as variables
• msg.to as the destination for outgoing messages
• Queue-based delivery with configurable concurrency
• msg.stop = true to cancel queued sends

The whatsapp-config node is the single owner of the WhatsApp connection. Both whatsapp.out and whatsapp.in reference it — they never create connections of their own.

Available Nodes

This section lists currently implemented channels.

WhatsApp

whatsapp-config

A config node that owns the connection to WhatsApp. Both whatsapp-out and whatsapp-in nodes reference one config node. Connection management (connect, disconnect, QR scan, session) lives exclusively in this node.

whatsapp-out

Renders a Nunjucks template from the incoming message and sends the result as a WhatsApp message via the configured connection.

whatsapp-in

Receives incoming WhatsApp messages and emits them into the flow. Multiple whatsapp.in nodes can share the same config without creating duplicate sessions.

Each incoming text message produces a Node-RED message with:

| Property | Content | |---|---| | msg.payload | Message text | | msg.from | Sender phone number (e.g. 5511999999999) | | msg.fromJid | Full WhatsApp sender ID (e.g. [email protected]) | | msg.chatId | Chat identifier — phone number for DMs, numeric ID for groups | | msg.timestamp | Unix timestamp (seconds) | | msg.messageId | Unique message ID | | msg.raw | Original whatsapp-web.js Message object |

Optional filters: allowed senders (list), group messages (allow/block), own messages (include/exclude).

Modes (WhatsApp)

Free — whatsapp-web.js

Connects to WhatsApp through a browser session running on the server.

• No API account or cost required
• Requires a one-time QR scan from the WhatsApp mobile app
• Session is stored on the server and reused across restarts
• Subject to WhatsApp's unofficial client restrictions

Official — WhatsApp Business API

Connects through the Meta WhatsApp Business API (hosted by Meta or a BSP).

• Requires a Business account and API token
• No QR code — authenticates via token
• Suitable for production and high-volume use

Install

cd ~/.node-red
npm install @inteli.city/node-red-contrib-notification-collection

Quick Start

Free mode (whatsapp-web.js)

1. Drag a whatsapp-config node into any flow (or create one from inside a whatsapp-out node)
2. Set Mode to Free (whatsapp-web.js)
3. Open the config node editor, click Connect
4. Scan the QR code that appears using WhatsApp on your phone
5. Status changes to Connected
6. Drag a whatsapp-out node, select the config, set a template
7. Send a message with msg.to set to the recipient's number

Official mode

1. Create a whatsapp-config node, set Mode to Official (WhatsApp Business API)
2. Enter your Base URL, Phone Number ID, and Bearer Token
3. Drag a whatsapp-out node and select the config
4. Send a message with msg.to set to the recipient's number

Receiving messages (whatsapp.in)

Quick start

1. Add a whatsapp-config node and connect it (QR scan, if not already done)
2. Drag a whatsapp.in node into the flow
3. Select the same config node
4. Wire the output to a debug node and deploy
5. Send a WhatsApp message to the connected number — it appears in the debug panel

Example: echo bot

[whatsapp.in] → [function] → [whatsapp.out]

The function node reads msg.chatId and constructs a reply:

msg.to = msg.chatId;
msg.payload = "You said: " + msg.payload;
return msg;

Wire whatsapp.in → function → whatsapp.out (same config). Every incoming text message gets echoed back to the sender.

Filters

| Field | Default | Effect | |---|---|---| | Allowed senders | (blank) | One per line or comma-separated. Blank = allow all. Enter plain phone numbers — no @c.us suffix. Exact match. A message passes if it matches any listed value. | | Allow group messages | ✓ | Uncheck to drop all group chat messages | | Include own messages | ✗ | Check to also forward messages sent by the connected account |

v1 scope

Only text messages are forwarded. Media (images, audio, files) and other message types are silently ignored.

Message format

msg.to (required)

For WhatsApp nodes, the destination phone number. Digits only, including country code. No + or spaces.

msg.to = "5511999999999"   // Brazil, SP
msg.to = "14155552671"     // US

You can also set a fallback To in the node editor. If msg.to is present it always takes priority.

msg.payload

Available in the template as {{ payload }}.

msg.payload = "Hello from Node-RED!"

Stopping the queue

msg.stop = true   // cancels all queued and running sends for that node

Template system

Templates use Nunjucks syntax. Message properties are available directly — no msg. prefix.

| Variable | Value | |---|---| | {{ payload }} | msg.payload | | {{ topic }} | msg.topic | | {{ flow.get("key") }} | Flow context | | {{ global.get("key") }} | Global context | | {{ env.MY_VAR }} | Environment variable |

Objects and arrays are automatically JSON-stringified.

Examples:

Hello {{ payload }}!

Order {{ payload.id }} is {{ payload.status }}.

{% if payload.urgent %}URGENT: {% endif %}{{ payload.message }}

Override the template at runtime by setting msg.template.

Queue behavior

Each out node has its own independent queue. The Queue field sets the maximum number of messages sent in parallel.

Queue = 1, 4 messages arrive:
→ 1 sent immediately
→ 3 wait
→ each starts as the previous finishes

The node status shows live queue state:

0 (0/1) web      ← idle
2 (1/1) web      ← 2 waiting, 1 sending

Use Queue = 1 when order matters. Increase for throughput when the channel allows it.

Connection states (WhatsApp web mode)

| State | Meaning | Action | |---|---|---| | disconnected | Not connected, session may exist | Click Connect | | initializing | Browser starting up | Wait | | waiting_for_qr | QR ready to scan | Scan with WhatsApp | | ready | Connected and sending | — | | failed | Auth or startup error | Click Connect to retry |

Disconnect stops the connection but keeps the session on disk — next connect will not need a QR.

Forget Session deletes the session from disk — next connect will show a new QR.

Future channels

This collection is designed to support additional notification channels over time.

Planned directions include:

• Email
• SMS

These will follow the same configuration and delivery pattern.

Limitations

• No retries — failed sends are not automatically retried
• No template includes — {% include %}, {% extends %}, and {% import %} are not supported
• No msg. prefix in templates — use {{ payload }}, not {{ msg.payload }}
• WhatsApp web mode — uses an unofficial client and may be affected by WhatsApp policy changes

Package renamed

This package was renamed from @inteli.city/node-red-contrib-whatsapp. If you were using the previous version, reinstall using the new package name:

npm uninstall @inteli.city/node-red-contrib-whatsapp
npm install @inteli.city/node-red-contrib-notification-collection

Existing flows are unaffected — node type identifiers have not changed.