Notification channels

Introduction

Featurenotify Notifications reach users inside the app and by mail. Some messages belong where people already are: the team's Slack channel, a chat with your Teams bot, a text message, WhatsApp, a push notification on their phone. Five more channels take the same notification there:

Every delivery over these channels is a row in notification_deliveries. Status callbacks from the providers move it to delivered, read or failed, a reply of STOP opts the number out, and each channel has a fake for tests.

Routing a notifiable

A notifiable says where each channel reaches it. Every route_* method has a default of None, which skips the channel for that recipient, so implement the ones you use:

use navree::notify::{Notifiable, TeamsRoute, USER_NOTIFIABLE_TYPE};
use uuid::Uuid;

/// An employee as the recipient of notifications.
#[derive(Clone, Debug)]
pub struct Employee {
    pub id: Uuid,
    pub email: String,
    /// Any format; read as E.164 in `notify.sms.default_region`.
    pub mobile: Option<String>,
    /// Saved when the Teams bot was installed for them.
    pub teams: Option<TeamsConversation>,
}

#[derive(Clone, Debug)]
pub struct TeamsConversation {
    pub service_url: String,
    pub conversation_id: String,
}

impl Notifiable for Employee {
    fn notifiable_type(&self) -> &'static str {
        USER_NOTIFIABLE_TYPE
    }

    fn notifiable_id(&self) -> String {
        self.id.to_string()
    }

    fn route_mail(&self) -> Option<String> {
        Some(self.email.clone())
    }

    fn route_sms(&self) -> Option<String> {
        self.mobile.clone()
    }

    fn route_whatsapp(&self) -> Option<String> {
        self.mobile.clone()
    }

    fn route_teams(&self) -> Option<TeamsRoute> {
        let teams = self.teams.as_ref()?;
        Some(TeamsRoute::conversation(
            teams.service_url.clone(),
            teams.conversation_id.clone(),
        ))
    }
}

Web push has no route method: it sends to the push subscriptions the notifiable saved (see web push).

Rendering for each channel

A notification renders itself for each channel its via lists, as it does for mail and the database. This one goes to the app's notification list, the employee's Teams chat, their phone and their browsers:

use navree::notify::{
    Channel, Notifiable, Notification, SmsMessage, TeamsMessage, Urgency, WebPushMessage,
};
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};

/// A training module is due today.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct TrainingDue {
    pub module: String,
    pub url: String,
}

impl Notification for TrainingDue {
    const TYPE: &'static str = "training.due";

    fn via(&self, _notifiable: &dyn Notifiable) -> Vec<Channel> {
        vec![
            Channel::Database,
            Channel::MicrosoftTeams,
            Channel::Sms,
            Channel::WebPush,
        ]
    }

    fn to_database(&self, _notifiable: &dyn Notifiable) -> Option<Value> {
        Some(json!({ "title": "Training due", "message": self.module, "url": self.url }))
    }

    fn to_teams(&self, _notifiable: &dyn Notifiable) -> Option<TeamsMessage> {
        Some(
            TeamsMessage::new(format!("**{}** is due today.", self.module))
                .summary("Training due")
                .card(json!({
                    "type": "AdaptiveCard",
                    "version": "1.4",
                    "body": [{ "type": "TextBlock", "text": self.module, "weight": "Bolder", "wrap": true }],
                    "actions": [{ "type": "Action.OpenUrl", "title": "Start", "url": self.url }]
                })),
        )
    }

    fn to_sms(&self, _notifiable: &dyn Notifiable) -> Option<SmsMessage> {
        Some(SmsMessage::new(format!(
            "{} is due today: {}. Reply STOP to opt out.",
            self.module, self.url
        )))
    }

    fn to_web_push(&self, _notifiable: &dyn Notifiable) -> Option<WebPushMessage> {
        Some(
            WebPushMessage::new("Training due")
                .body(&self.module)
                .url(&self.url)
                .tag("training")
                .urgency(Urgency::High),
        )
    }
}

Send it as any notification, with notifier.send(&employee, TrainingDue { .. }). A message that names its own recipient (SlackMessage::to, TeamsMessage::to, SmsMessage::to, WhatsAppMessage::to) goes there instead of to the notifiable's route, so a notification can post to a team channel whoever it was sent to:

fn to_slack(&self, _notifiable: &dyn Notifiable) -> Option<SlackMessage> {
    Some(
        SlackMessage::new(format!("Deployed {}", self.version))
            .blocks(json!([{
                "type": "section",
                "text": { "type": "mrkdwn", "text": format!("*Deployed* `{}`", self.version) }
            }]))
            .to(SlackRoute::channel("C0123456789")),
    )
}

The new channels go out like mail and broadcasts: after the request's transaction commits, or as one notify.send job each with notify.queue on (see queueing). The job carries the rendered message, so a worker sends exactly what the request rendered. For web push, the subscriptions are read when the job runs.

Configuration

Each channel reads its own table of the notify section. A channel with nothing configured still works where it needs nothing (Slack and Teams webhooks); the others fail with NotifyError::Unavailable until they have a driver.

[notify]
deliveries = true                 # record each delivery in notification_deliveries

[notify.slack]
bot_token = ""                    # APP_NOTIFY__SLACK__BOT_TOKEN (xoxb-...)

[notify.teams]
app_id = "6f3c1f0e-2a4b-4c5d-8e9f-0a1b2c3d4e5f"   # the Azure Bot's app id
app_password = ""                 # APP_NOTIFY__TEAMS__APP_PASSWORD
tenant = "botframework.com"       # or your tenant id for a single-tenant bot

[notify.sms]
driver = "twilio"                 # twilio | vonage | sns | log
from = "+15550001111"             # a number, a sender id, or a Twilio messaging service MG...
default_region = "US"             # numbers written without a country code
status_callback = "https://api.acme.test/api/webhooks/notify/twilio"

[notify.whatsapp]
driver = "meta"                   # twilio | meta | log
from = "+15550001111"             # Twilio only

[notify.web_push]
public_key = "BGp8...Q"           # from `notify:vapid`
private_key = ""                  # APP_NOTIFY__WEB_PUSH__PRIVATE_KEY
subject = "mailto:[email protected]"
ttl_secs = 86400

[notify.twilio]
account_sid = "AC0123456789abcdef0123456789abcdef"
auth_token = ""                   # APP_NOTIFY__TWILIO__AUTH_TOKEN

[notify.meta]
phone_number_id = "105589345678901"
access_token = ""                 # APP_NOTIFY__META__ACCESS_TOKEN

The slack, twilio, vonage, sns and meta tables also take an endpoint, the API's base URL, for a regional endpoint or a local mock server in tests. A driver configured without its credentials fails the boot with the keys it needs (notify.sms.driver \twilio` needs notify.twilio.account_sid and notify.twilio.auth_token`). Tokens, secrets and keys are read from the configuration and never serialized, logged or shown in errors; keep them in environment variables.

Slack

A SlackRoute is an incoming webhook or a channel:

use navree::notify::SlackRoute;

SlackRoute::webhook("https://hooks.slack.com/services/T000/B000/XXXX"); // a channel's webhook
SlackRoute::channel("C0123456789");                                    // with notify.slack.bot_token
SlackRoute::channel("C0123456789").connection(install_id);              // with a connection's bot token

A webhook route is posted the message's JSON. A channel route calls chat.postMessage with the channel (or a user id, for a direct message), authenticated with notify.slack.bot_token, or with the bot token of an integrations connection when the route names one: each customer workspace that installed your Slack app posts with its own token.

Slack's answer is the message's ts for a channel route, recorded as the delivery's provider id; a webhook returns no id. A refusal is a ChannelError::Refused with Slack's code (channel_not_found, no_service, invalid_payload).

Microsoft Teams

A TeamsRoute is an incoming webhook or a conversation with your bot:

use navree::notify::TeamsRoute;

// A channel's workflow: "Post to a channel when a webhook request is received".
TeamsRoute::webhook("https://prod-12.westeurope.logic.azure.com/workflows/.../invoke?sig=...");
// A personal chat, group chat or channel the bot is in.
TeamsRoute::conversation("https://smba.trafficmanager.net/emea/", "a:1Xyz...");
TeamsRoute::conversation(service_url, conversation_id).connection(tenant_bot_id);

A webhook receives the message as an Adaptive Card: the message's card, or one holding its text. A conversation receives a proactive message from your bot, POST {serviceUrl}/v3/conversations/{id}/activities, with the text, the summary and the card attached. Save the service URL and conversation id when the bot is installed for someone (its conversationUpdate activity), and return them from route_teams.

The bot authenticates with a Bot Framework token for notify.teams.app_id (client credentials, cached until a minute before it expires), or with an integrations connection's token when the route names one, for a bot registered in each customer's tenant.

A conversation's answer is the new activity's id. A refusal carries the Bot Framework's code, such as BotNotInConversationRoster when the bot was removed from the conversation.

SMS

Pick a driver with notify.sms.driver:

Numbers are read as E.164 with navree-validation's Phone, in notify.sms.default_region when they have no country code: (415) 555-0100 with default_region = "US" is +14155550100. A number that isn't valid fails the channel with NotifyError::InvalidRecipient, and its delivery is recorded as failed.

Opt-outs

Text messages must stop when the recipient asks. The SMS and WhatsApp channels keep an opt-out list per channel, notification_opt_outs, and skip a number on it: its delivery is recorded as opted_out, and send succeeds.

A number is opted out when:

• it replies with an opt-out keyword: STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, OPTOUT or REVOKE, matched on the whole message, ignoring case and trailing punctuation (Twilio's own OptOutType wins when it sends one);
• the provider refuses it as opted out: Twilio's error 21610, the WhatsApp Cloud API's 131050, also when it arrives in a status callback;
• your code opts it out.

START, YES, UNSTOP and OPTIN opt it back in. Replies reach the app through the provider callbacks. In code, inject Arc<OptOuts>:

use navree::notify::{Channel, OptOutSource, OptOuts};

// A user turned texts off in their settings.
opt_outs
    .opt_out(Channel::Sms, "(415) 555-0100", OptOutSource::Manual)
    .await?;
opt_outs.is_opted_out(Channel::Sms, "+14155550100").await?; // true
opt_outs.opt_in(Channel::Sms, "+14155550100").await?;        // and back on
let all = opt_outs.list(Channel::Sms).await?;                // newest first

Numbers are normalized the same way as for sending, so every format of one number is one entry. Inside a request handler, these writes join the request's transaction.

WhatsApp

Pick a driver with notify.whatsapp.driver: twilio (the Messages API with whatsapp: addresses, sharing notify.twilio's credentials with SMS), meta (the WhatsApp Cloud API, POST /{api_version}/{phone_number_id}/messages) or log.

WhatsApp takes free text only inside the 24-hour window after the recipient last wrote to you. Outside it, send an approved template:

fn to_whatsapp(&self, _notifiable: &dyn Notifiable) -> Option<WhatsAppMessage> {
    Some(WhatsAppMessage::template(
        WhatsAppTemplate::new("order_shipped", "en_US").parameter(&self.order),
    ))
}

Web push

Web push shows a notification on the user's device, through the push service of their browser (Firebase Cloud Messaging for Chrome, Mozilla's for Firefox, Apple's for Safari). Each message is encrypted for one subscription (RFC 8291, aes128gcm) and signed with your VAPID key (RFC 8292, ES256 on ring through navree_crypto), so only that browser can read it and push services know it comes from you.

1. Generate a VAPID key pair

   navree notify:vapid

   [notify.web_push]
   public_key = "BGp8...Q"
   private_key = "q1dX...4"
   subject = "mailto:[email protected]"

   Keep the private key secret. A new pair invalidates every subscription, so generate it once per app.

2. Subscribe in the browser

   The signed-in user's browser fetches the public key from GET /api/notifications/push-key, subscribes, and saves the subscription. With the typed client:

   import { unwrap } from "@navree/client";
   import { api } from "@/lib/api/client";
   
   export async function enablePush() {
     const { public_key } = await unwrap(api.GET("/api/notifications/push-key"));
     const registration = await navigator.serviceWorker.register("/sw.js");
     const subscription = await registration.pushManager.subscribe({
       userVisibleOnly: true,
       applicationServerKey: public_key,
     });
     await unwrap(api.POST("/api/notifications/push-subscriptions", { body: subscription.toJSON() }));
   }

3. Show the notification in the service worker

   self.addEventListener("push", (event) => {
     const { title, body, icon, url, tag, data } = event.data.json();
     event.waitUntil(self.registration.showNotification(title, { body, icon, tag, data: { url, ...data } }));
   });
   
   self.addEventListener("notificationclick", (event) => {
     event.notification.close();
     event.waitUntil(clients.openWindow(event.notification.data.url ?? "/"));
   });

The routes are part of the notification routes (notify.routes), for the signed-in user:

A subscription needs an https endpoint (http only on localhost), a P-256 p256dh key and an auth secret of at least 16 bytes; otherwise the answer is a 400 naming the field. Saving an endpoint that is already saved moves it to the signed-in user, with the new keys: a browser profile belongs to whoever signed in on it last. In code, PushSubscriptions has subscribe, unsubscribe, of(notifiable_type, notifiable_id) and delete.

The channel sends to every subscription of the notifiable when the notification goes out. A push service that answers 404 or 410 has dropped the subscription, so it is deleted, and the notification still succeeds. With notify.deliveries on, a retried notify.send job skips the subscriptions an earlier attempt reached, so a failure at one push service doesn't push twice to the others. Push endpoints come from browsers, so the driver calls them with the default SSRF policy: an endpoint at an internal address is refused.

The service worker receives payload(): a JSON object with title and each of body, icon, url, tag and data that is set. One push message holds at most 3993 bytes of it.

The delivery log

With notify.deliveries on and DatabaseModule in the app, every attempt over the five channels is a row of notification_deliveries, the navree-orm model NotificationDelivery:

A retried notify.send job updates its row instead of adding one. Status callbacks only move a delivery forward, because providers send them out of order: sent becomes anything, delivered becomes read, and read, failed and opted_out are final.

Inject Arc<DeliveryLog> to read it: for_notification(id) lists a notification's deliveries and find_by_message(provider, id) finds one by its provider id. For anything else, query the model:

use navree::notify::NotificationDelivery;
use navree::orm::Model as _;

let failed = NotificationDelivery::query()
    .where_(NotificationDelivery::CHANNEL.eq("sms"))
    .where_(NotificationDelivery::STATUS.eq("failed"))
    .latest_by(NotificationDelivery::CREATED_AT)
    .get(&db)
    .await?;

Provider callbacks

Twilio, Vonage and the WhatsApp Cloud API report what happened to each message, and forward the replies people send: a status callback moves its delivery forward, a STOP opts the number out. With the webhooks feature on too (both are in full), WebhooksModule receives them for you, verified like any incoming webhook. It mounts one public route for each of these sources you configure, as long as NotifyModule is in the app:

[webhooks.incoming.twilio]
secret = ""             # APP_WEBHOOKS__INCOMING__TWILIO__SECRET: the auth token

[webhooks.incoming.vonage]
secret = ""             # APP_WEBHOOKS__INCOMING__VONAGE__SECRET: the signature secret

[webhooks.incoming.meta]
secret = ""             # APP_WEBHOOKS__INCOMING__META__SECRET: the app secret
verify_token = ""       # APP_WEBHOOKS__INCOMING__META__VERIFY_TOKEN

The Twilio route answers with an empty TwiML <Response/>, so a reply sends nothing back; the others answer 200. A request that fails verification is a 400 and changes nothing. Meta's GET ?hub.mode=subscribe handshake is answered with the challenge when its hub.verify_token matches. Twilio signs the URL it called, so behind a proxy set webhooks.incoming.twilio.url to the callback route's public URL, or let the proxy pass X-Forwarded-Proto and X-Forwarded-Host; the source's url is one URL, so a Twilio route of your own on the same source needs the forwarded headers.

To receive them on a route of your own, verify with the source and hand the body to the log. ChannelCallback::from_twilio, from_vonage and from_meta read the providers' payloads, and DeliveryLog::ingest applies them:

use navree::notify::{ChannelCallback, DeliveryLog};
use navree::prelude::*;
use navree::webhooks::{Twilio, VerifiedWebhook};

#[injectable]
pub struct SmsHooks {
    log: Arc<DeliveryLog>,
}

#[controller("/hooks/sms")]
impl SmsHooks {
    /// `POST /api/hooks/sms`: Twilio statuses and replies.
    #[post("/")]
    #[public]
    async fn twilio(&self, hook: VerifiedWebhook<Twilio>) -> Result<NoContent> {
        self.log
            .ingest(ChannelCallback::from_twilio(hook.body()))
            .await?;
        Ok(NoContent)
    }
}

ingest returns Ingested { updated, opted_out, opted_in }. A status for a message id the log doesn't know is ignored.

Connections from integrations

A Slack or Teams route can name a connection of Integrations: SlackRoute::channel("C0123").connection(id), TeamsRoute::conversation(url, conversation).connection(id). The driver then sends with that connection's current access token, refreshed when it is due: a workspace's Slack install posts with its own bot token, and a bot registered in a customer's Microsoft tenant sends with an app-only token of a microsoft connection whose scope set asks for https://api.botframework.com/.default.

IntegrationsModule provides the tokens (dyn ConnectionTokens) when the integrations and notify features are both on; both are in full. To keep tokens elsewhere, register your own Arc<dyn ConnectionTokens>. A route that names a connection in an app without one fails with a ChannelError::Config that says so.

Testing

Each channel has a fake that records what it is asked to send: SlackFake, TeamsFake, SmsFake, WhatsAppFake and WebPushFake. Install it in place of the driver with override_value::<dyn SmsDriver>(fake.driver()), and so on. The SMS and WhatsApp fakes also play the provider: deliver, fail (and read for WhatsApp) report a status for the last message to a number, and reply sends the app a message from one, through the same DeliveryLog::ingest the real callbacks use.

use navree::notify::{
    Channel, Notifier, OptOuts, SmsDriver, SmsFake, TeamsDriver, TeamsFake, WebPushDriver,
    WebPushFake,
};
use navree::prelude::*;
use navree::testing::TestApp;

#[tokio::test]
async fn due_training_is_texted_and_stop_opts_out() {
    let sms = SmsFake::new();
    let app = TestApp::builder()
        .temp_database()
        .config("notify.routes", false)
        .config("notify.sms.default_region", "US")
        .module(DatabaseModule::from_config())
        .module(NotifyModule::from_config())
        .override_value::<dyn SmsDriver>(sms.driver())
        .override_value::<dyn TeamsDriver>(TeamsFake::new().driver())
        .override_value::<dyn WebPushDriver>(WebPushFake::new().driver())
        .build()
        .await;
    let notifier = app.get::<Notifier>().await;
    let priya = employee();
    let due = TrainingDue {
        module: "Phishing basics".into(),
        url: "https://learn.acme.test/m/42".into(),
    };

    notifier.send(&priya, due.clone()).await.unwrap();
    let texts = sms.sent_to("+14155550100");
    assert!(texts[0].body.starts_with("Phishing basics is due today"));

    // The provider reports it delivered; Priya replies STOP.
    sms.deliver(app.ctx(), "+14155550100").await.unwrap();
    sms.reply(app.ctx(), "+14155550100", "STOP").await.unwrap();

    notifier.send(&priya, due).await.unwrap();
    assert_eq!(sms.sent().len(), 1, "no more texts after STOP");
    let opt_outs = app.get::<OptOuts>().await;
    assert!(
        opt_outs
            .is_opted_out(Channel::Sms, "+14155550100")
            .await
            .unwrap()
    );
}

Every fake has assert_sent(|sent| ..) and assert_nothing_sent(), and records deliveries as provider fake. To test a real driver against a local mock server, give its table an endpoint: the HTTP client's SSRF policy allows a configured endpoint's host.

Errors

A driver that does not send fails its channel with NotifyError::Channel { channel, source }, and the delivery is recorded as failed; the other channels still deliver. source is a ChannelError:

NotifyError::InvalidRecipient is a number that isn't valid E.164, and NotifyError::Unavailable a channel without a driver, such as SMS without notify.sms.driver. Messages never contain message bodies, tokens or webhook URLs.