npm package: @inteli.city/node-red-contrib-notification-collection
Description: A collection of Node-RED nodes for sending notifications, designed for multiple channels and currently supporting WhatsApp.
Latest version: 1.0.0

# 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](https://mozilla.github.io/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

```bash
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 }}`.

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

### Stopping the queue

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

---

## Template system

Templates use [Nunjucks](https://mozilla.github.io/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:**

```nunjucks
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:

```bash
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.