Notifications

The notification system delivers event-driven alerts to users through WebSocket, push, and email channels. Rules define which events trigger notifications and how they are delivered.

The notification system delivers alerts to users when relevant events occur on the platform. Notifications can be delivered in real time (WebSocket), as push notifications (mobile), or via email.

How notifications work

Platform event
  → Notification service evaluates rules
    → Matching rule found
      → Resolve recipients
      → Generate notification content
      → Deliver via configured channels
        ├── WebSocket (real-time)
        ├── Push (mobile)
        └── Email

An event is published to the event bus (for example, conversation.message_posted)
The notification service evaluates the event against registered notification rules
If a rule matches, it resolves the recipients, generates the notification content, and dispatches it
Deliverers handle channel-specific formatting and transport

Notification rules

A notification rule defines:

Property	Description
Event pattern	Which events trigger this rule (for example, `conversation.message_posted`)
Priority	Notification priority level (affects display and delivery behavior)
Content template	Template for the notification title and body (supports dynamic values from the event payload)
Delivery channels	Which channels to use: WebSocket, push, email, or a combination
Recipient resolver	Logic that determines who receives the notification (for example, all conversation participants except the sender)

Built-in rules

The platform includes default notification rules for common events:

New message — notifies conversation participants when a new message is posted
Conversation created — notifies relevant users when they are added to a conversation
Task completed — notifies the task owner when a long-running task finishes
Task failed — notifies the task owner when a task fails

You can define additional notification rules to cover your application-specific events. Custom rules follow the same structure as built-in rules and can reference any event published to the event bus.

Delivery channels

WebSocket

For connected clients. WebSocket delivery is instant — the notification appears in the UI as soon as it's generated. This is the primary delivery channel for users actively using the platform.

Push

For mobile clients. Push notifications are sent through platform push services and appear on the user's device even when the app is not in the foreground.

Email

For offline delivery. Email notifications are sent when the user is not connected via WebSocket or push, ensuring important alerts are not missed.

Notification lifecycle

Created — the notification is generated from a matched rule
Delivered — sent to the user through one or more channels
Read — the user has seen and acknowledged the notification

Users can mark notifications as read through the API or UI.

Event Bus — the event system that drives notifications
Real-time Messaging — WebSocket delivery infrastructure

Notifications

On this page