Preferences

Novu provides a way to store subscriber preferences. This allows subscribers, your users, to specify and manage their preferences and customize their notifications experience.

Levels of preferences:

• Workflow channel preferences
• Subscriber channel preferences per workflow
• Subscriber global preferences

Workflow channel preferences

Each workflow has its own channel preferences. By default, all channel preferences are enabled. If disabled, the subscriber will not receive notifications for that channel step.

Steps to manage workflow channel preferences:

Critical workflows

In some cases, you don't want the subscriber to be able to unsubscribe from mandatory notifications such as Account Verification, Password Reset, etc...

In those cases, you can mark a workflow as critical in the workflow channel preferences. Critical workflows are not displayed in subscriber preferences, so subscribers cannot change preferences for that workflow.

Subscriber global preferences

Subscribers can set global channel preferences, which apply across every workflow. For instance, if there are 10 workflows and a subscriber wants to disable SMS notifications for all of them, they can do so with global preferences instead of changing each workflow.

Global preferences act as the subscriber's baseline. If the same subscriber later sets a preference for one specific workflow, that more specific choice wins for that workflow. See Priority of preferences.

Subscriber channel preferences per workflow

For each workflow, each subscriber has their own channel preferences. Subscribers can manage these preferences from the <Inbox />{" "} Preferences view.

Priority of preferences

Novu resolves preferences per channel. It layers each type of preference on top of the previous one, from the most general to the most specific, and the most specific layer that defines a channel wins:

1. Workflow channel preferences defined in code with the Framework
2. Workflow channel preferences set in the dashboard
3. Subscriber global preferences
4. Subscriber channel preferences per workflow

So a subscriber's per-workflow choice takes precedence over their global choice, and both take precedence over the workflow defaults.

The one exception is critical workflows. When a workflow is marked as critical, both subscriber layers are discarded and the workflow channel preferences decide on their own.

flowchart TD
    startNode([Should this channel send?]) --> isCritical{Workflow marked as critical?}
    isCritical -->|Yes| useWorkflow[Use the workflow channel preference]
    isCritical -->|No| hasWorkflowPref{Subscriber set a preference for this workflow?}
    hasWorkflowPref -->|Yes| useSubscriberWorkflow[Use the subscriber preference for this workflow]
    hasWorkflowPref -->|No| hasGlobalPref{Subscriber set a global preference for this channel?}
    hasGlobalPref -->|Yes| useSubscriberGlobal[Use the subscriber global preference]
    hasGlobalPref -->|No| useWorkflow
    useWorkflow --> resolved{Resolved value enabled?}
    useSubscriberWorkflow --> resolved
    useSubscriberGlobal --> resolved
    resolved -->|Yes| sendAllowed[Send notification]
    resolved -->|No| blocked[Do not send]

Examples:

1. If the email channel is enabled in workflow channel preferences but the subscriber disabled email globally, they will not receive email notifications for this workflow.
2. If the subscriber disabled email globally but enabled email for this specific workflow, they will receive email notifications for this workflow. The per-workflow preference is more specific than the global one.
3. If the in-app channel is enabled in workflow channel preferences and the workflow is marked as critical, subscribers cannot change their preferences and will always receive in-app notifications.

Subscriber preferences APIs

Subscriber preferences can be retrieved and updated using following APIs: