Rules, events & fallback

Rules are the heart of the module: an event pattern in, a channel cascade out. This is where “patch failed → the ops Slack channel, else Microsoft Teams” is expressed — no hook PHP to write. Rules live under Addons → ImpulseNotify → Rules.

1. The event catalog

One catalog defines every event a rule can match, its category, and the variables a template may use. Events come from WHMCS hooks, from events ImpulseCore relays, and from the module’s own scans:

Category	Events (rule pattern)	Source
Billing	Invoice created, paid, payment reminder, cancelled, refunded (invoice.created, invoice.paid, invoice.reminder, invoice.cancelled, invoice.refunded)	WHMCS hooks
Orders	Order placed, paid, accepted, flagged as fraud (order.placed, order.paid, order.accepted, order.fraud)	WHMCS hooks
Service	Activated, suspended, unsuspended, terminated, upgraded/downgraded (service.created, service.suspended, service.unsuspended, service.terminated, service.upgraded)	ImpulseCore
Service	Service password changed (service.password_changed)	WHMCS hook
Support	Ticket opened, staff reply, client reply, closed (ticket.opened, ticket.admin_reply, ticket.user_reply, ticket.closed)	WHMCS hooks
Support	Response SLA breached (ticket.sla_breach)	sla_scan cron
Domains	Domain expiring at 60 / 30 / 14 / 7 / 1 days (domain.expiring)	domain_expiry_scan cron
Security	Client login, client password changed, admin login (client.login, client.password_changed, admin.login)	WHMCS hooks
Security	Critical CVE detected, patch/reboot/rollback failed, patch/reboot completed, maintenance deferral cap reached (security.cve_critical, security.patch_failed, security.patch_completed, security.deferral_cap_reached)	ImpulseCore Security & Maintenance

ImpulseCore relays WHMCS’s server-module create, suspend, unsuspend, terminate and package-change events, so service notices fire for services of any WHMCS server module — ImpulseNotify doesn’t need to know how a service was provisioned. The domain scan covers active domains and sends each notice once. The SLA scan raises an admin alert, at most once a day per ticket, for tickets left in Open or Customer-Reply past a response-time limit. No limit is set by default and the admin area has no setting for one in this release, so the scan stays off.

Declared but not emitted yet

invoice.overdue, client.login_failed and admin.login_failed are in the catalog, but nothing emits them yet — WHMCS has no reliable hook for them. Rules for them are accepted and stay silent until a source lands.

2. Anatomy of a rule

Click + Add rule for the four-step wizard (Trigger → Audience → Channel → Review & enable), or Advanced form for every field, including fallback hops:

• Rule name — your label.
• Event — an individual catalog event, or a family: invoice.*, order.*, service.*, security.*.
• Custom event pattern — an fnmatch-style glob such as ticket.*; it overrides the Event choice.
• Audience — Client resolves to the client’s verified contact for the channel’s type; Admin / operator fans out to matching Staff Recipients.
• Recipient (optional) — an explicit phone number, chat id, URL, email address or Pushover key. It always wins; leave it empty to resolve automatically.
• Channel (hop 0) — the enabled channel that sends immediately, plus up to two fallback hops.
• Priority — an integer 0–100; lower runs first.
• Enabled — tick to activate.

Every enabled rule whose pattern matches an event fires — priority sets the order, not exclusivity. On an unlicensed install, creating a rule counts toward the 5-rule cap; editing, enabling, disabling and deleting rules always work.

Pre-stage future rules

A pattern that matches no known event is saved with a warning, not refused — so you can create rules for events that arrive in a later release.

3. Fallback cascades

A cascade has up to three hops. Hop 0 sends immediately; each fallback hop has a Wait:

• Wait 0 — escalate only when the previous hop fails outright: the provider rejects it, or it is still failing after its retries.
• Wait of 30 minutes or more — also escalate when a channel with delivery receipts (WhatsApp or SMS) reports sent but not delivered for that long. No stock template routes events to WhatsApp or SMS in this release, so this applies once templates for those channels exist.

Delivery anywhere in a cascade marks the remaining hops skipped, so a chain never double-delivers. A fallback hop can’t repeat the previous hop’s channel — retries already re-try the same channel. The fallback_escalate cron task (every 5 minutes) drives cascades for messages created in the last 48 hours.

Each hop needs an address for its own channel. A client-audience rule looks up the client’s verified contact for the new channel type and checks their consent again. An admin-audience or explicit recipient is reused only when both channels take the same kind of address — a URL for Webhook, Slack, Discord and Teams (an empty recipient uses each channel’s saved URL), a chat id for Telegram, a phone number for WhatsApp and SMS — so a hop between kinds, such as Telegram → Email, is skipped.

Example

An admin-audience rule for security.patch_failed with no recipient: hop 0 = the ops Slack channel, fallback hop 1 = a Microsoft Teams channel with a wait of 0. If Slack rejects the alert, or is still failing after its retries, the Teams card goes out instead.

4. Templates

Every rule-routed message is rendered from a template for its event × channel type × language. The language comes from the client’s contact, then Settings → Default language, then en. Bodies use named tokens such as {invoice.total} — plain substitution against the event’s variable list, never code execution.

Stock templates ship for:

• the diagnostics test message, on every channel type except SMS (on WhatsApp it points at Meta’s hello_world);
• the four infrastructure security events, on Telegram, Webhook, Slack, Discord, Teams, Pushover and Email.

No template editor in this release

The admin area can’t create or edit templates yet. A rule that routes another event — billing, orders, service, support, domains, logins — to a channel without a template for it skips that message. The exception is a Webhook / n8n channel, which needs no template: it posts the event’s variables as JSON. To get WHMCS billing, order, ticket, service or domain notices onto chat, SMS or email today, either route them to a Webhook channel and on from your automation, or use WHMCS’s own Notification Rules through the ImpulseNotify provider (see WHMCS native notification rules), which sends WHMCS’s own text.

WhatsApp is approved-template-only. A business-initiated WhatsApp message must use a Meta-approved template, and the module checks the template’s approval status when a message is queued. See WhatsApp onboarding.

5. Audience resolution & staff routing

Client audience

A client-audience rule resolves to the client’s own verified contact for the channel’s type. Clients hold WhatsApp, Telegram and SMS contacts, which they add and verify themselves on the client-area Notification Preferences page at index.php?m=impulsenotify. The module doesn’t add a link to it, so link the page from your client area’s navigation. The page offers only channel types you have an enabled channel for.

• Verification: the client requests a 6-digit code, valid for 10 minutes, with 5 attempts per code and at most 3 codes per contact per hour. Telegram users can instead click Connect Telegram, which links their chat directly — this needs the Telegram webhook from Connecting channels.
• Consent: clients choose, per category and channel, what they receive. Billing, Services, Support, Domains and Security are on by default; Offers & news is off unless they opt in. Order events aren’t a separate choice; they count as transactional. A category a client has switched off is honoured even when the rule names an explicit recipient.
• Who can change preferences: the account owner, a user with WHMCS’s Modify Master Account Profile permission, or an admin logged in as the client — who can opt the client out of anything but never into Offers & news.

Admin audience & rotations

An admin-audience rule with no recipient fans out to your Staff Recipients. Each recipient is a person or group with a name, one or more channels — Telegram, SMS, Email or Pushover, each with its own address — and an optional category filter (none ticked = every category). Each matching, enabled recipient gets the message on their channel of the same kind as the rule’s channel.

Recipients sharing a rotation group take weekly turns by their rotation order (the ISO week number modulo the group’s size) — a lightweight on-call rotation with no separate scheduling tool. Recipients without a group always receive.

When no staff recipient matches, Webhook, Slack, Discord, Teams and Pushover channels deliver to the channel’s saved destination; other channel types skip the message. On an unlicensed install, staff recipients are capped at 2.

6. Reliability behind every rule

Every message a rule produces becomes a durable queue row — nothing is fire-and-forget:

• Duplicate protection — each queued message is keyed on the event, the record it’s about (an invoice, order or ticket, for example), the client, rule, channel and recipient, and the UTC day, so double-fired hooks and re-run cron tasks collapse to one send. The same key means a repeat of an event on the same record the same day — a second staff reply on one ticket, say — isn’t sent again.
• Retry backoff — temporary failures retry after 60s → 5m → 15m → 1h → 6h and are dead-lettered at attempt 6. Permanent failures, such as an invalid number, are marked failed without retrying.
• Rate limits — a global per-minute, a per-channel per-minute and a per-client per-day ceiling (120, 60 and 20 by default, under Settings → Rate limits) for rule-routed messages; WHMCS Notification Provider sends get the global and per-channel ceilings. Messages over a limit are dropped, not queued — raise the ceilings before a large invoice run.
• Quiet hours — an optional nightly window that defers marketing-category messages only. None of the built-in events is in that category, so transactional traffic is never held.
• Kill switch — Pause ALL sends drops new events instead of queuing them; messages already queued wait until you switch it off.
• Dry-run mode — rule-routed messages render and are logged as skipped (dry-run) without any provider being called. Any queued message that comes due while dry-run is on — including retries and bulk messages queued before you turned it on — is marked skipped and never sent.

Validate before you rely on it

Turn on Dry-run mode under Settings → Delivery controls, trigger the events your rules target, and check that the Logs tab shows them as skipped (dry-run). Diagnostics → Activity shows why a matched rule produced no message — for example a missing template, an unverified contact, or a rate limit. Turn dry-run off when the routing looks right.

7. Manual & bulk messages

The Manual Message tab sends without a rule — operator intent, not an event.

• Single send: pick a channel, enter a recipient and a message. It’s queued and sent straight away. The text goes out literally — tokens aren’t substituted. Sending the same message again sends it again, but reloading the page after a send doesn’t.
• Bulk send: choose an audience — all active clients, clients with an active service of a product, or clients with unpaid invoices — and a WhatsApp, Telegram or SMS channel. Preview is mandatory: it counts the clients with a verified contact on that channel type, lists the first ten, and reports clients without one as excluded. Send then queues one message per recipient for the queue_drain cron task, which sends up to 50 per run. Bulk sends bypass the rate limits and don’t check clients’ notification preferences or STOP opt-outs, so use them only for messages your clients expect.

On WhatsApp, single and bulk sends go out as the approved test template rather than your text. Manual and bulk sends count toward the dev-mode daily cap.

8. Data retention & erasure

Under Settings → Data retention & privacy:

• Delivery-log retention — 90 days by default. The log stores masked recipients only.
• Inbound callback retention — 30 days by default for processed provider callbacks such as delivery receipts and replies.
• Redact message content — optionally clears rendered message content from finished queue rows; the daily prune clears rows about a day after they finish.

Settings → GDPR — Erase a client previews and then deletes a client’s notification contacts and consent records, and scrubs their queued and logged messages; you confirm by typing ERASE. Deleting a client in WHMCS triggers the same erasure automatically.

9. WHMCS native notification rules (optional)

WHMCS’s own Notification Rules can also deliver through ImpulseNotify channels: the module registers as a WHMCS Notification Provider, so a rule under System Settings → Notifications can pick an ImpulseNotify channel and recipient. These sends use WHMCS’s notification text and need no ImpulseNotify template, and they bypass the addon’s rules, consent and staff routing. WhatsApp channels aren’t offered. Setup is in Installation & activation.