Notifications¶

Revel has a multi-channel notification system that delivers messages through in-app notifications, email, and Telegram. The system is designed to be extensible, user-configurable, and respectful of user preferences.

Architecture¶

flowchart LR
    Trigger["Event Trigger<br/>(service layer)"] --> Dispatcher["Notification Dispatcher"]
    Dispatcher --> InApp["In-App Channel"]
    Dispatcher --> Email["Email Channel"]
    Dispatcher --> Telegram["Telegram Channel"]

    InApp --> DB[(Database)]
    Email --> Celery["Celery Worker"]
    Telegram --> Celery

    Celery --> SMTP["SMTP Server"]
    Celery --> TGBot["Telegram Bot API"]

    Prefs["User Preferences"] -.->|"filter channels"| Dispatcher

Channels¶

Notification Types¶

The following notification types are supported across all channels:

Event Notifications¶

Invitation & Membership¶

Tickets & Payments¶

Transactional types (bypass the digest)¶

The transactional types (TRANSACTIONAL_TYPES in notifications/enums.py) are the payment, ticket and subscription lifecycle types: payment_confirmation, ticket_created, ticket_cancelled, ticket_refunded, and the five subscription_* receipts and alerts.

These are time- and money-sensitive, so they always deliver immediately and bypass the digest cadence. Together with account_banned and system_announcement they form MANDATORY_TYPES, which users can't opt out of. See Email Sending & Opt-Out Policy. Every other type honours the user's digest setting (digest users get the in-app notification now and the email in the next digest sweep).

The three staff_ticket_* alert types and the two org_custom_domain_* owner types (White-Label) are also in TRANSACTIONAL_TYPES, so they skip the digest, but they are not in MANDATORY_TYPES: the recipient can opt out of them.

Waitlist & Availability¶

Questionnaires¶

Potluck¶

Whitelist Requests¶

Account¶

Organization setup¶

Announcements¶

Following¶

Template Structure¶

Templates are organized by channel under src/notifications/templates/notifications/:

notifications/
  templates/
    notifications/
      in_app/
        event_cancelled.md
        event_open.md
        ...
      email/
        event_cancelled.html
        event_cancelled.txt
        ...
      emails/
        digest.html
        digest.txt
      telegram/
        event_cancelled.md
        event_open.md
        ...

User Preferences¶

Users configure their notification preferences per channel and per type. The preference model supports:

• Per-channel toggles: Enable/disable each channel independently
• Per-type toggles: Fine-grained control over which notifications to receive
• Digest mode: Batch notifications into periodic summaries instead of sending individually (does not apply to the transactional types, which always deliver immediately)
• Per-organization announcement mute: Stop one organization's announcements without touching anything else

Implementation Details¶

The notification system is implemented in notifications/service/, which includes:

• Dispatcher: Routes notifications to the appropriate channels based on user preferences
• Eligibility checks: Determines which users should receive a given notification (e.g., only attendees of an event)
• Reminder scheduling: Schedules event reminders via Celery Beat periodic tasks
• Digest batching: Aggregates notifications into periodic digest emails
• Unsubscribe handling: Manages per-type and per-channel opt-outs, one-click List-Unsubscribe, the per-organization announcement mute and the email suppression list (see Email Sending & Opt-Out Policy)

Notifications are triggered from the service layer via Django signals and direct dispatcher calls. Delivery for email and Telegram channels is always asynchronous via Celery tasks.

Admin Pings (Pushover & Discord)¶

Separate from the main user-facing notification system, Revel dispatches admin-only pings when operationally interesting events happen on the platform. These never reach end users and do not create Notification records; they go directly to Pushover and/or a Discord webhook.

Each channel self-skips when its config is missing:

• Pushover requires PUSHOVER_USER_KEY + PUSHOVER_APP_TOKEN.
• Discord requires DISCORD_ADMIN_WEBHOOK_URL.

Dispatch is gated by SiteSettings flags:

• notify_user_joined → new-user pings (both channels)
• notify_organization_created → new-organization pings (both channels)

Tasks live in accounts/tasks.py (user) and events/tasks.py (organization); signals in the corresponding signals.py dispatch them via transaction.on_commit so any related rows (e.g., Referral) are visible when the task runs. All tasks retry with exponential backoff (½/4 min, max 3 attempts).