Skip to main content

​
What are Notifications?

Notifications are how Connie tells you (and your teammates) that something happened — a workflow failed, a task is due, a billing event needs attention, an inbox account disconnected. Every notification flows through a single dispatcher with three properties:
  • A category (e.g. workflow_failures, tasks_assigned)
  • A severity (low, normal, high, urgent)
  • A set of channels the dispatcher fans it out to — bell, email, or toast
Categories map 1:1 to user preferences, so each member of your workspace can mute or re-route notifications they don’t want.

​
Channels

Bell

The in-app notification panel. Persisted history, badge count, mark-read / dismiss / archive.

Email

Per-event emails via Resend. Cap-enforced for high-volume categories, bypassed for critical alerts.

Toast

Transient in-product banners for live feedback (e.g. “import complete”). Not persisted.
The bell panel currently updates via a 30-second poll on GET /api/notifications. Realtime delivery is on the roadmap.

​
Severity → channel routing

The dispatcher picks channels based on the event’s severity: The frequency cap prevents a runaway loop from flooding you with the same email 200 times. Critical events (payment failures, billing disputes, a paused production schedule) always punch through.

​
Categories

Each workspace member sees a per-category preference matrix in Settings → Notifications. The defaults are tuned per category — workflow_failures is on for both bell and email; crm_imports is toast-only. The full category list, grouped by domain:
121 distinct event types are wired into the dispatcher today, spanning every module. Each event is tagged with one of these categories so user preferences can mute it cleanly.

​
What a notification looks like

Every notification carries enough context to render itself and to link back to the thing it’s about:
The link field is the deep-link the bell panel uses for the click-through. related_type and related_id let the UI render a contextual chip (“workflow #123”) and group multiple notifications about the same entity.

​
Approval tasks

Some workflows pause and require a human to approve, reject, or comment before continuing — these surface as approval task notifications. When an approval gate fires:
  • The dispatcher emails everyone eligible to approve (no double-bell — bell is written separately by the legacy approval system)
  • Read state is shared across approvers: once one teammate reads the notification, it’s marked read for everyone assigned to the same task
  • If the approval times out, the run is cancelled and a follow-up notification is sent
Use markAllNotificationsRead with workspace_id set to wipe your unread count for one workspace at a time without touching others.

​
API reference

The Notifications API is read-only from a user’s perspective — workspaces dispatch notifications internally, and the surface is just for the bell panel.

List notifications

Paginated history, filtered by priority, category, related entity, read/dismissed state.

Mark read

Per-notification or workspace-wide read-state updates.

Dismiss

Hide a notification without marking it read.

Mark all read

Bulk-clear unread count, optionally scoped to one workspace.