> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications Overview

> Bell, email, and toast notifications across every Connie module — with per-category preferences and severity-aware routing.

## 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

<CardGroup cols={3}>
  <Card title="Bell" icon="bell">
    The in-app notification panel. Persisted history, badge count, mark-read / dismiss / archive.
  </Card>

  <Card title="Email" icon="envelope">
    Per-event emails via Resend. Cap-enforced for high-volume categories, bypassed for critical alerts.
  </Card>

  <Card title="Toast" icon="message">
    Transient in-product banners for live feedback (e.g. "import complete"). Not persisted.
  </Card>
</CardGroup>

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:

| Severity | Bell | Email | Frequency cap |
| - | - | - | - |
| **Critical** | ✅ | ✅ | Bypassed — always fires |
| **High** | ✅ | ✅ | 10-minute window per user × category |
| **Medium** | ✅ | ✅ | 30-minute window |
| **Low** | ✅ | — | 30-minute window |

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:

| Domain | Categories |
| - | - |
| **Workspace** | `payment_subscription`, `credit_warnings`, `member_joined`, `role_changes` |
| **Flows** | `workflow_failures`, `workflow_completions`, `approval_tasks`, `schedule_paused` |
| **Inbox** | `inbox_disconnections`, `inbox_scheduled_failures` |
| **CRM** | `tasks_assigned`, `tasks_due_overdue`, `tasks_daily_digest`, `mentions` |
| **Pages** | `kb_sync_failures`, `kb_sync_completions`, `kb_connector_reconnect` |
| **AI** | `ai_long_task_completions`, `ai_browser_task_results` |
| **Tools** | `connectors_disconnected`, `connectors_expiring`, `connectors_scope_change`, `connectors_reconnect_failed`, `connectors_mcp_unreachable` |

<Note>
  **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.
</Note>

***

## What a notification looks like

Every notification carries enough context to render itself and to link back to the thing it's about:

```json theme={null}
{
  "id": "n_01J...",
  "category": "workflow_failures",
  "priority": "high",
  "type": "WORKFLOW_RUN_FAILED",
  "title": "Workflow failed",
  "message": "\"Enrich new contacts\" failed during the LinkedIn step.",
  "link": "/workspace/abc/workflows/wf_123/runs/run_456",
  "related_type": "workflow",
  "related_id": "wf_123",
  "read": false,
  "is_dismissed": false,
  "metadata": { "error_step": "linkedin_enrich" }
}
```

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.

<CardGroup cols={2}>
  <Card title="List notifications" icon="list" href="/api-reference/notifications/list-notifications">
    Paginated history, filtered by priority, category, related entity, read/dismissed state.
  </Card>

  <Card title="Mark read" icon="check" href="/api-reference/notifications/mark-notification-read">
    Per-notification or workspace-wide read-state updates.
  </Card>

  <Card title="Dismiss" icon="xmark" href="/api-reference/notifications/dismiss-notification">
    Hide a notification without marking it read.
  </Card>

  <Card title="Mark all read" icon="circle-check" href="/api-reference/notifications/mark-all-notifications-read">
    Bulk-clear unread count, optionally scoped to one workspace.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.