notify-router

A multi-channel notification router for Xano. Define channels (email, SMS, Slack, push, webhook…), let users set per-topic preferences on each channel, and then fan-out a single notify call into a delivery per opted-in channel. Every delivery is recorded for audit/retry/analysis.

This is a module, not a full app: no frontend, no auth, and no actual SMTP/SMS/Slack integration — it writes delivery rows with status=sent and hands them to you. Point a task at the nr_delivery table to actually dispatch them (or swap the simulation in nr_dispatch for real provider calls).

What you get

• 3 tables — nr_channel, nr_preference, nr_delivery
• Function nr_dispatch — given a user + topic + subject/body, resolves channels, checks preferences, creates delivery rows. Call it from any XanoScript.
• HTTP API notify-router — admin endpoints plus a generic notify endpoint callable from any service

Install

npm install -g @xano/cli
xano profile:wizard

cd backend
xano workspace:push

Creates 3 tables, 1 function, 1 api group, and 6 endpoints.

API surface

POST   /api:notify-router/channels                       { key, name, channel_type, active?, target_template?, config? }
GET    /api:notify-router/channels                       ?active=true

PUT    /api:notify-router/preferences                    { user_id, channel_key, topic, enabled }   # upsert
GET    /api:notify-router/users/{user_id}/preferences    list prefs + enriched channel info

POST   /api:notify-router/notify                         { user_id, topic, subject?, body?, metadata? }
GET    /api:notify-router/deliveries                     ?user_id&topic&status&page&per_page

channel_type is one of: email, sms, push, webhook, slack, in_app.

Usage

1. Configure channels

B=https://YOUR-INSTANCE.n7d.xano.io

curl -XPOST $B/api:notify-router/channels -H 'Content-Type: application/json' -d '{"key":"email","name":"Email","channel_type":"email"}'
curl -XPOST $B/api:notify-router/channels -H 'Content-Type: application/json' -d '{"key":"sms","name":"SMS","channel_type":"sms"}'
curl -XPOST $B/api:notify-router/channels -H 'Content-Type: application/json' -d '{"key":"slack","name":"Slack","channel_type":"slack"}'

2. Set preferences per user + topic

curl -XPUT $B/api:notify-router/preferences -H 'Content-Type: application/json' -d '{"user_id":"42","channel_key":"email","topic":"alerts","enabled":true}'
curl -XPUT $B/api:notify-router/preferences -H 'Content-Type: application/json' -d '{"user_id":"42","channel_key":"sms","topic":"alerts","enabled":true}'
curl -XPUT $B/api:notify-router/preferences -H 'Content-Type: application/json' -d '{"user_id":"42","channel_key":"slack","topic":"alerts","enabled":false}'

3. Fire a notification

curl -XPOST $B/api:notify-router/notify \
  -H 'Content-Type: application/json' \
  -d '{"user_id":"42","topic":"alerts","subject":"Server down","body":"DB unreachable","metadata":{"severity":"critical"}}'

Response:

{
  "user_id": "42",
  "topic": "alerts",
  "active_channels": 3,
  "matched_prefs": 2,
  "deliveries_created": 2,
  "deliveries": [ /* two rows — email + sms */ ]
}

Slack is skipped because that user's preference for slack:alerts is false.

4. Call from XanoScript

function.run "nr_dispatch" {
  input = {
    user_id : $auth.id|to_text,
    topic   : "order.shipped",
    subject : "Your order has shipped",
    body    : "Tracking: " ~ $tracking,
    metadata: { order_id: $order.id }
  }
} as $dispatch

Schema

• nr_channel — key (unique), name, channel_type (enum), active, target_template, config (json)
• nr_preference — user_id (text) + channel_id + topic + enabled
• nr_delivery — per-delivery row: status (queued / sent / failed / skipped), sent_at, error, metadata

Design notes

• Opt-in model. A channel-topic pair has to have an explicit preference row with enabled=true to deliver. Missing preferences don't deliver. Change this policy in nr_dispatch if you prefer opt-out.
• Text user IDs. Plug in any id scheme; the module doesn't assume a user table.
• Delivery recorded, actual send is up to you. nr_dispatch writes rows with status=sent as a simulation. Wire a Xano task to nr_delivery with status=queued and your real provider to make this production-ready, or edit nr_dispatch directly to call your provider inline.
• topic is free-form. Convention-over-schema — use whatever namespace you like (billing.invoice, security.login_anomaly, marketing.weekly_digest).

License

MIT.