​

Notifications hub

The Notifications hub is the bell in the top bar and the page behind it (/notifications). It is your org’s tenant-scoped inbox for platform events: delivery alerts, spend-cap and wallet warnings, compliance flags, AI agent escalations, security alerts, and system announcements. It is deliberately separate from the other two inbox-like surfaces: Inbox holds customer conversations, and Team Chat holds operator chatter. Anything the platform itself needs to tell you lands in Notifications. This page is an orientation map, not a walkthrough. Each section links the deeper page that owns the steps.

​

The surfaces at a glance

​

Notification taxonomy

Notifications are emitted by every pillar of the platform: SMS, WhatsApp, email, voice, verify, AI agents, and billing. Each notification carries a kind — the closed enum of concrete events, such as credit_low, agent_handoff_pending, or new_signin_from_new_device — grouped into a category that your preferences key on: billing, security, messaging, campaigns, agents, and system. Kinds fall into three families:

• Alerts — something needs your action now: a wallet that hit zero and paused outbound, a campaign that finished with errors, an AI agent escalation waiting for a human, a conversation that breached its SLA.
• Anomalies — something deviated from baseline: unusual billing activity, an email DNS regression that puts deliverability at risk, a webhook endpoint auto-disabled after repeated failures.
• System notes — lifecycle records: number orders completing, regulatory bundles approved or declined, port status changes, teammate role changes, API key creates and revokes.

Every kind renders with a category icon and a severity — info, warning, or error — and the feed’s kind filter mirrors the same enum, so a kind can never be invisible to filtering. The full kind-to-icon table lives in Read and filter the notifications feed. For how a single event fans out to the bell, an immediate email, or a scheduled digest, see The notification model. For which control owns which outlet — per-user preference vs org digest vs org webhook sink — see Notification digest vs. per-user preferences.

​

Browsing, filtering, muting, and archiving

• Browse — the feed is a virtualised, cursor-paginated list; a Load more control pages history in, and only the visible window of rows mounts no matter how deep you scroll. Above the feed, Active platform alerts pin persistent issue states — outbound paused, KYC pending, compliance risk, webhook backlog, number document expiry — so the center is never empty while a real issue is outstanding.
• Filter — three filters combine freely: Unread only, Kind (the full enum, group-ordered the way you think about it), and Severity. A malformed filter value never errors the page; it is ignored and the feed loads unfiltered.
• Mute — muting is per category, on Settings → Notifications: switch a category’s channel off for yourself, or drop its frequency to daily or weekly. Security kinds bypass every mute — sign-ins from new devices, 2FA changes, password or email changes, and API key events always mint a row and deliver, so a hijacked session cannot silence the takeover signal.
• Archive — there is no separate archive shelf; dismissal and expiry are the archive. Dismiss a user-scoped row from its hover control (a ~5 second undo window catches mistakes) and it leaves your feed; org-wide rows show no dismiss control and expire on their own clock. Rows whose expiry has passed drop out of every list and unread count; rows without one persist until dismissed.
• Read state — opening a row marks it read, hover reveals the read check, and Mark all read clears the badge in one click. Read state stays in sync across open browser tabs.

​

Real-time push with a poll safety net

The page subscribes to the live stream (GET /api/v1/notifications/stream, server-sent events), so a new row lands without a refresh. A 30-second poll sits behind it: if a stream frame is missed — a laptop resuming from sleep between heartbeats, a dropped connection — the poll self-corrects. A feed that looks up to ~30 seconds stale is the fallback working, not a bug, and the bell badge polls on the same cadence so it never sticks on a stale number. The stream caps at 50 concurrent connections per tenant, enforced cluster-wide, and requires a browser user-agent and a trusted origin. The mechanics and a freshness decision table live in Configure notification channels.

​

Per-channel delivery settings

Each member of the org tunes their own matrix on Settings → Notifications: three channel toggles per category — email, push, and webhook — plus a frequency (immediate by default, daily, or weekly). Defaults are on until you change them; security is exempt and always on. The three destinations come from the notification model’s fan-out (The notification model); here is where each one is tuned:

• In-app — the bell and the feed receive every row your preferences do not mute, and every security row regardless. This is the only surface that always has the full picture.
• Email — immediate per event by default, or rolled into the org digest: an owner/admin opt-in on Settings → Notifications → Digest with a daily or weekly cadence and an optional category list (an empty list means all six categories). Worked example: setting the campaigns frequency to daily turns N campaign emails into one aggregated digest email.
• Push — per-user push subscriptions follow the same category matrix; they are personal and distinct from org-level sinks.
• Webhook — the per-user webhook toggle delivers your categories to your endpoint; Developer → Webhooks is the org-level sink that fans developer events out regardless of any member’s opt-out. Teams commonly terminate either at a Slack incoming webhook or an ops bot, which is the Slack fan-out path. Signing and payload contract: Webhook events.

The per-category matrix, the digest API (GET/PUT /api/v1/notifications/digest/settings, PUT restricted to owner and admin), and the always-on security list are documented with worked samples in Configure notification channels.

​

Sub-account notification recipients

If you operate sub-accounts, rate-sheet emails and account-balance alerts can route to a per-sub-account recipient list instead of the org default, with inheritance up the reseller chain and a safe fallback when nothing is configured. See Sub-account notification recipients.

​

Where to go next

• The notification model — event fan-out, categories, channels, and digests.
• Triage the Notification Center — what raises a notification and how to work it day to day.
• Read and filter the notifications feed — the kind taxonomy, icons, filters, and read state.
• Configure notification channels — per-user toggles, the digest API, and freshness debugging.
• Notification digest vs. per-user preferences — what each control owns and which alerts ignore your mutes.
• Sub-account notification recipients — per-sub-account routing for rate-sheet and balance alerts.
• Notifications API — list, unread count, mark-read, dismiss, and the SSE stream.