@inteli.city/node-red-contrib-notification-collection 1.0.4
A collection of Node-RED nodes for sending notifications, designed for multiple channels and currently supporting WhatsApp and email.
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). Currently supported channels are WhatsApp and email. Additional channels such as SMS are planned.
Concept
This structure applies to all channels.
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
msgproperties as variables msg.toas the destination for outgoing messages- Queue-based delivery with configurable concurrency
msg.stop = trueto 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-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).
Email follows the same config-node pattern as WhatsApp: an email-config node owns authentication and shared server settings, and the two regular nodes reference it.
email-config
Owns the shared email account: credentials (userid, password), authentication type (Basic / XOAuth2 / None), SMTP server (used by email.out), and IMAP/POP3 server + protocol (used by email.in). All shared validation happens here — if the config is incomplete, the referencing nodes refuse to start with a consistent error.
Authentication and shared transport settings are not overridable at runtime. The XOAuth2 access-token path is fixed in config; only the token value flows via msg (tokens are short-lived and refreshed upstream).
email.out
References an email-config node and sends a rendered Nunjucks template as an email. Follows the same outbound shape as whatsapp.out: destination from msg.to (with node-level To as an optional fallback), Nunjucks templating via the shared renderer, and a per-node queue for concurrency control.
The subject comes from msg.topic. msg.to takes priority over the node's To field when both are present; if neither is set the node fails with a clear error.
Supports Basic auth and XOAuth2 (for GMail app passwords, Outlook/Exchange OAuth2, etc.) — the access-token value flows via msg while the path stays fixed in email-config. Binary msg.payload is attached automatically; structured attachments can be passed via msg.attachments in nodemailer format.
email.in
References an email-config node and polls an IMAP or POP3 mailbox, emitting one Node-RED message per email not previously seen.
Each message exposes:
| Property | Content |
|---|---|
msg.topic |
Email subject |
msg.payload |
Plain-text body |
msg.html |
HTML body (if present) |
msg.from |
Sender address |
msg.date |
Date the email was sent |
msg.header |
Full header object (includes to, cc, etc.) |
msg.attachments |
Array of attachment objects |
Can poll on an interval or fetch only when triggered by an incoming message. IMAP supports folder selection, search criteria, and optional "mark read" / "delete" dispositions.
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)
- Drag a whatsapp-config node into any flow (or create one from inside a whatsapp-out node)
- Set Mode to
Free (whatsapp-web.js) - Open the config node editor, click Connect
- Scan the QR code that appears using WhatsApp on your phone
- Status changes to Connected
- Drag a whatsapp-out node, select the config, set a template
- Send a message with
msg.toset to the recipient's number
Official mode
- Create a whatsapp-config node, set Mode to
Official (WhatsApp Business API) - Enter your Base URL, Phone Number ID, and Bearer Token
- Drag a whatsapp-out node and select the config
- Send a message with
msg.toset to the recipient's number
Receiving messages (whatsapp.in)
Quick start
- Add a whatsapp-config node and connect it (QR scan, if not already done)
- Drag a whatsapp.in node into the flow
- Select the same config node
- Wire the output to a debug node and deploy
- 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:
- 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.
