Notifications

A notification type is an event-class admins manage centrally (e.g. conversation.assigned, sla.breached, analytics.scheduled_report_completed). Users then opt-in or opt-out of each type on their own preferences page.

Heads up: definition CRUD on this page is live and per-user preferences resolve from these rows. The cross-system event dispatcher that fires on domain events (conversation transitions, SLA breaches, presence changes, etc.) and the in-app notification bell are still in flight. Today the only event-fired notifications come from the scheduled-report worker.

Creating a notification type

1. Settings → Notifications → + New.
2. Event type — snake_case <resource>.<event> (e.g. conversation.assigned). Must be unique within the tenant. Immutable after create.
3. Name (English) and Name (Arabic) — both required. Shown to users in their preferences picker.
4. Default channels — tick one or more of:
   • In-app — stored as the default delivery channel.
   • Email — delivered via the default email server. Per-user opt-in via the preferences picker.
   • WhatsApp — stored but not yet delivered (Phase 6 BSP). Labelled “Not yet enforced” inline.
5. Applicable roles — chip multi-select of roles that should see this notification in their preferences. Leave empty for “all roles.”
6. Mandatory notification — when ticked, the row cannot be deleted by admins. Used for compliance event types that must stay registered.

Per-user preferences

Each user has their own notification preferences page where they can override the defaults: pick which channels (in-app / email / WhatsApp) each event type fires on, or mute the type entirely. Mandatory types cannot be muted by users.

Where notifications fire

Today, only the scheduled-report worker writes notification history (delivering an “Your report is ready” email when an analytics export completes). The broader event-bus dispatcher that fires on conversation transitions, SLA breaches, presence changes, etc. is still being wired up. The in-app bell consumer that surfaces unread notifications is part of the same in-flight work.

Until the dispatcher lands, this page is most useful as the catalogue of event types that will eventually fire, and as the config surface for per-user preferences.

Best practices

• Keep event-type strings stable. Renaming them requires a delete + recreate (you’ll lose existing preferences and history) — type the snake_case name carefully.
• Use the <resource>.<event> pattern consistently: conversation.assigned, conversation.transferred, sla.breached, agent.offline.
• Mark only true compliance types as Mandatory. Locking too many notifications creates noise users can’t suppress.
• Restrict by Applicable roles when the event genuinely only affects one role (e.g. an “agent.offline” alert is for supervisors, not the agent themselves).

Deleting a type

Deleting a non-mandatory row permanently removes it and cascade-deletes any per-user preferences and history rows. Mandatory rows cannot be deleted from the UI.