@inteli.city/node-red-contrib-notification-collection 1.0.0

A collection of Node-RED nodes for sending notifications, designed for multiple channels and currently supporting WhatsApp.

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

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

All channels share the same principles:

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

Available Nodes

This section lists currently implemented channels.

WhatsApp

whatsapp-config

A config node that owns the connection to WhatsApp. Every whatsapp-out node references one config node.

whatsapp-out

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

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

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.

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)

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.