Novu Manage Preferences
Apps & Automationnovu-manage-preferencesNovu Manage Preferences is an Agent Skill for apps & automation published in the novuhq/novu repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Configure notification preferences in Novu at the workflow and subscriber level. Set default channel preferences (email, SMS, push, chat, in-app), mark preferences as read-only or subscriber-editable, and manage subscriber-specific overrides. Use when setting up notification opt-in/opt-out, configuring per-channel delivery preferences, or building a preferences management UI.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/novuhq/novu/blob/HEAD/docs/.mintlify/skills/manage-preferences/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/novu-manage-preferences, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Manage Preferences
Novu has a two-level preference system:
- Workflow defaults — configured in the dashboard for UI based workflows or via code in framework based workflows, apply to all subscribers.
- Subscriber overrides — set by end users, override workflow defaults
Workflow-Level Preferences
Set default preferences when defining a workflow with @novu/framework:
import { workflow } from "@novu/framework";
const alertWorkflow = workflow("system-alert", execute, {
preferences: {
all: { enabled: true, readOnly: false },
channels: {
email: { enabled: true },
sms: { enabled: false },
push: { enabled: true },
chat: { enabled: false },
inApp: { enabled: true },
},
},
});
Authoring workflows in code? See
framework-integrationfor the full Framework setup, Bridge Endpoint, step controls, and deployment.
Channel Types
| Channel | Description |
|---|---|
email | Email notifications |
sms | SMS text messages |
push | Mobile/web push notifications |
chat | Slack, Discord, Teams, etc. |
inApp | In-app Inbox notifications |
Read-Only Preferences
Set readOnly: true to hide a workflow's channels from the Preferences UI — subscribers can't toggle them on or off:
const criticalAlertWorkflow = workflow("critical-alert", execute, {
preferences: {
all: { enabled: true, readOnly: true }, // subscriber CANNOT disable
},
});
readOnly vs critical — pick the right one
These are different mechanisms with different guarantees. See design-workflow/references/severity-and-critical.md for the full matrix.
| Flag | What it does |
|---|---|
preferences.all.readOnly: true | UI only. Hides the workflow from the Preferences UI so subscribers can't toggle it. |
critical: true (workflow-level) | Runtime. Bypasses subscriber preferences, skips digest, runs without delays. |
If you need the notification to always be delivered (account suspended, security alert, password reset), set critical: true — readOnly: true alone won't override existing subscriber overrides at runtime.
Optional (Subscriber-Editable) Preferences
const marketingWorkflow = workflow("weekly-newsletter", execute, {
preferences: {
all: { enabled: true, readOnly: false }, // subscriber CAN disable
channels: {
email: { enabled: true },
sms: { enabled: false }, // off by default, subscriber can enable
},
},
});
Subscriber-Level Preferences
Subscribers can override workflow defaults (unless readOnly: true).
Get Subscriber Preferences
import { Novu } from "@novu/api";
const novu = new Novu({
secretKey: process.env.NOVU_SECRET_KEY,
});
const preferences = await novu.subscribers.preferences.list({
subscriberId: "subscriber-123",
});
Update Subscriber Preferences
await novu.subscribers.preferences.update(
{
workflowId: "weekly-newsletter",
channels: {
email: false, // opt out of email
inApp: true, // keep in-app
},
},
"subscriber-123"
);
Global Preferences
Update preferences across all workflows by omitting workflowId:
await novu.subscribers.preferences.update(
{
channels: {
sms: false, // disable SMS for all workflows
},
},
"subscriber-123"
);
Preference Resolution Order
When Novu determines whether to deliver a notification:
- Subscriber workflow preference (most specific) — subscriber's override for this specific workflow
- Subscriber global preference — subscriber's default across all workflows
- Workflow default — developer-defined default in code
- System default — all channels enabled
The most specific preference wins. If a subscriber disables email for a specific workflow, that takes precedence even if their global email preference is enabled.
Preferences UI Component
React
import { Inbox } from "@novu/react";
function App() {
return (
<Inbox
applicationIdentifier="YOUR_NOVU_APP_ID"
subscriberId="subscriber-123"
subscriberHash="HMAC_HASH"
>
{/* The Preferences panel is built into the Inbox */}
</Inbox>
);
}
The <Inbox /> component includes a built-in Preferences panel accessible via the settings icon.
Standalone Preferences
Use the <Preferences /> component independently:
import { Inbox, Preferences } from "@novu/react";
function PreferencesPage() {
return (
<Inbox
applicationIdentifier="YOUR_NOVU_APP_ID"
subscriberId="subscriber-123"
>
<Preferences />
</Inbox>
);
}
Common Patterns
Critical Alerts (Always On)
preferences: {
all: { enabled: true, readOnly: true },
}
Subscribers cannot opt out. Use for security alerts, payment notifications, legal notices.
Marketing (Opt-Out Friendly)
preferences: {
all: { enabled: true, readOnly: false },
channels: {
email: { enabled: true },
sms: { enabled: false },
},
}
Subscribers can toggle channels. SMS is off by default.
In-App Only by Default
preferences: {
all: { enabled: false },
channels: {
inApp: { enabled: true },
},
}
Only in-app is on. Subscribers can enable other channels if desired.
Common Pitfalls
readOnly: trueis per-workflow, not per-channel — you setreadOnlyon thealllevel. Individual channels inherit it.- Subscriber overrides don't apply to
readOnlyworkflows — if the workflow is read-only, subscriber preferences are ignored. enabled: falsein the workflow default means the channel is off — subscribers can still enable it (unlessreadOnly: true).- The Preferences UI only shows non-readOnly workflows — read-only workflows are hidden from the subscriber's preference panel.
- Global preferences apply across all non-readOnly workflows — they're a convenient "disable all email" setting, but workflow-specific preferences take precedence.