Strapi Notifier

A first-class notification system for Strapi v5 admin panels. Adds a live bell icon to the sidebar, a full notification inbox, a runtime Settings panel, and a simple API to send notifications from anywhere in your Strapi application.

Install now

strapi-plugin-notifier

Features

Live bell icon — badge count updated by polling the server (interval configurable)
Notification inbox — filter by type, mark as read, dismiss, load more, clear all
Targeting — broadcast to all admins, or target by user ID or role code
Batch sending — send multiple notifications in one call, settings fetched once
Merge — collapse repeated notifications into one item with a count badge (fully configurable)
User opt-out — each admin user can mute individual notification types or opt out entirely
Declarative rules — trigger notifications from lifecycle hooks, eventHub events, or cron schedules — no code required beyond config/plugins.ts
Configurable — poll interval, page size, retention policy, UI accent colours, merge rules, and cleanup schedule
Settings panel — runtime configuration via Settings → Notifier (persisted in Strapi plugin store)
Retention cron — configurable cleanup schedule (default: 3 AM daily), respects maxDays and maxPerUser limits
Strapi v5 only

Installation

npm install strapi-plugin-notifier
# or
yarn add strapi-plugin-notifier

Enable the plugin in config/plugins.ts:

export default {
  notifier: {
    enabled: true,
    config: {
      // all fields are optional — see Configuration below
    },
  },
};

Configuration

All configuration is optional. Built-in defaults apply unless overridden.

// config/plugins.ts
export default {
  notifier: {
    enabled: true,
    config: {
      retention: {
        maxDays: 90,          // delete notifications older than N days
        maxPerUser: 500,      // cap notifications stored per user
        cleanupCron: '0 3 * * *', // cron schedule for cleanup job (default: 3 AM daily)
      },
      delivery: {
        pollIntervalMs: 30_000, // how often the Bell polls (ms)
        pageSize: 20,           // notifications per page in inbox
      },
      merge: {
        enabled: false,          // enable notification merging
        windowMinutes: 60,       // look back this many minutes for a merge candidate
        keyFields: ['title', 'type'], // fields that must match to merge
        countBadge: true,        // show "×N" badge on merged items in the inbox
        rewriteMessage: false,   // rewrite the message to "N× title" when merging
      },
      ui: {
        theme: {
          accent: {
            info:    '#4945ff',
            success: '#5cb85c',
            warning: '#f0ad4e',
            error:   '#ee5e52',
          },
        },
      },
    },
  },
};

Settings can also be updated at runtime from the Strapi admin panel under Settings → Notifier. Runtime settings take precedence over config/plugins.ts.

Sending notifications

Use the notifier service from anywhere in your Strapi code (services, controllers, lifecycles, webhooks):

const notifier = strapi.plugin('notifier').service('notifier');

// Broadcast to all admin users
notifier.broadcast({ title: 'Maintenance scheduled', type: 'warning' });

// Send to a specific role
notifier.toRole('strapi-editor', {
  title: 'New content submitted',
  message: 'An article is waiting for review.',
  url: '/content-manager/collection-types/api::article.article',
});

// Send to a specific admin user (by user ID)
notifier.toUser(42, {
  title: 'Your export is ready',
  type: 'success',
  url: '/uploads/export-2024.csv',
});

// Generic send with full control
notifier.send({
  title: 'Hello',
  message: 'World',
  type: 'info',
  url: 'https://example.com',
  to: { role: 'strapi-super-admin' },
});

Batch sending

Send multiple notifications in one call. Settings (including merge config) are fetched once and applied to all items — more efficient than looping over send().

await notifier.sendBatch([
  { title: 'New job application', type: 'info', to: { role: 'strapi-editor' } },
  { title: 'Export ready', type: 'success', to: { userId: 42 } },
  { title: 'Low disk space', type: 'warning' }, // broadcast
]);

Opt-out and merge rules are applied per item within the batch.

Notification options

Field	Type	Required	Default
`title`	`string`	Yes	—
`message`	`string`	No	—
`type`	`'info' \\| 'success' \\| 'warning' \\| 'error'`	No	`'info'`
`url`	`string`	No	—
`to`	`{ userId?: number; role?: string }`	No	broadcast

Notification merging

When merge.enabled is true, sending a notification whose key fields match an existing notification (created within windowMinutes) updates that notification instead of creating a new one.

Example — a form that can be submitted many times:

// config/plugins.ts
merge: { enabled: true, windowMinutes: 60, keyFields: ['title', 'type'], countBadge: true }

// In your lifecycle / service:
notifier.toRole('strapi-editor', {
  title: 'New job application',
  type: 'info',
});

After five submissions the inbox shows a single item: New job application ×5.

Merge key fields (title, type, url) — any combination. Two notifications are considered the same if all selected fields match AND the recipient matches AND the most recent one was created within the window.

Display options:

Option	Default	Effect
`countBadge`	`true`	Shows a coloured "×N" pill next to the title
`rewriteMessage`	`false`	Replaces the message with `"N× <title>"`

Both can be toggled from the Settings → Notifier → Merge panel at runtime.

User opt-out

Each admin user can control which notifications they receive. Opt-out is applied at query time so it covers broadcast and role-targeted notifications too.

Via the API

GET  /notifier/preferences/me
PUT  /notifier/preferences/me

Get current preferences:

GET /notifier/preferences/me
→ { "data": { "userId": 5, "globalOptOut": false, "mutedTypes": ["info"] } }

Mute info and success notifications:

PUT /notifier/preferences/me
Content-Type: application/json

{ "mutedTypes": ["info", "success"] }

Opt out entirely:

PUT /notifier/preferences/me
Content-Type: application/json

{ "globalOptOut": true }

Re-enable:

PUT /notifier/preferences/me
Content-Type: application/json

{ "globalOptOut": false, "mutedTypes": [] }

Preference fields

Field	Type	Default	Description
`globalOptOut`	`boolean`	`false`	Suppress all notifications for this user
`mutedTypes`	`NotificationType[]`	`[]`	Suppress only these notification types

Declarative rules

Instead of calling the notifier service in code, you can declare rules in config/plugins.ts. The plugin wires up the listeners at bootstrap — notifications fire automatically with no further code changes needed.

Three trigger types are supported: lifecycle, event, and cron.

`on: 'lifecycle'` — content-type create/update/delete

Fires when Strapi's DB lifecycle executes for a given content-type and action.

// config/plugins.ts
notifier: {
  enabled: true,
  config: {
    rules: [
      {
        on: 'lifecycle',
        model: 'api::article.article',
        action: 'afterCreate',          // afterCreate | afterUpdate | afterDelete | afterPublish | afterUnpublish
        notification: {
          title: 'New article: {{entry.title}}',
          message: 'Created by {{entry.createdBy.firstname}}',
          type: 'info',
          to: { role: 'strapi-editor' },
        },
      },
    ],
  },
},

entry in templates is the DB record produced by the lifecycle action (result for after-hooks, params.data for before-hooks).

`on: 'event'` — strapi.eventHub subscription

Fires on any named event published to Strapi's internal event hub (lifecycle events, media events, plugin events, or your own custom events emitted with strapi.eventHub.emit()).

{
  on: 'event',
  event: 'media.upload',              // any strapi.eventHub event name
  filter: { uid: 'api::article.article' }, // optional shallow key=value filter on payload
  notification: {
    title: 'File uploaded: {{media.name}}',
    type: 'info',
    to: 'broadcast',
  },
},

Custom events from your own services:

// In your service
strapi.eventHub.emit('order.placed', { order });

// In config/plugins.ts
{
  on: 'event',
  event: 'order.placed',
  notification: {
    title: 'New order: #{{order.id}}',
    message: '{{order.customerName}} — €{{order.total}}',
    type: 'success',
    to: { role: 'strapi-super-admin' },
  },
},

`on: 'cron'` — time-based notifications

Fires on a cron schedule. Standard 5-field cron expressions.

{
  on: 'cron',
  schedule: '0 9 * * 1',   // Every Monday at 9 AM
  notification: {
    title: 'Weekly reminder: review pending content',
    type: 'warning',
    to: { role: 'strapi-editor' },
  },
},

Notification templates

Every field in notification accepts either a static value or a function for dynamic content.

String interpolation — use {{path.to.field}} dot-notation to resolve values from the event context:

notification: {
  title: 'New order from {{entry.customer.name}}',
  message: 'Total: {{entry.total}} — shipped to {{entry.address.city}}',
}

Function templates — for logic that can't be expressed as a template string:

notification: {
  title: (ctx) => `${ctx.entry.priority === 'high' ? '🔴' : ''} Order #${ctx.entry.id}`,
  type: (ctx) => ctx.entry.priority === 'high' ? 'error' : 'info',
}

Targeting in rules

The to field supports the same options as the programmatic API, plus a userIdFrom path resolver:

Value	Behaviour
`'broadcast'` (or omitted)	Send to all admin users
`{ role: 'strapi-editor' }`	Send to all users with this role code
`{ userId: 42 }`	Send to a specific admin user
`{ userIdFrom: 'entry.createdBy.id' }`	Resolve user ID via dot-path into the event context — useful for "notify the author" patterns

// Notify the author when their content is rejected
{
  on: 'lifecycle',
  model: 'api::article.article',
  action: 'afterUpdate',
  when: (ctx) => ctx.entry.status === 'rejected',
  notification: {
    title: 'Your article was rejected',
    to: { userIdFrom: 'entry.createdBy.id' },
  },
},

`when` guard

Add a when function to conditionally skip the notification. Return false to suppress it.

{
  on: 'lifecycle',
  model: 'api::article.article',
  action: 'afterUpdate',
  when: (ctx) => ctx.entry.publishedAt != null,   // only fire when published
  notification: {
    title: 'Article published: {{entry.title}}',
    type: 'success',
    to: 'broadcast',
  },
},

when is not available on cron rules (there is no event context to filter on).

API routes

All routes require admin::isAuthenticatedAdmin. The plugin mounts under /notifier/.

Method	Path	Description
GET	`/notifier/notifications`	List notifications (paginated)
PUT	`/notifier/notifications/read-all`	Mark all as read
DELETE	`/notifier/notifications`	Clear all notifications
PUT	`/notifier/notifications/:id/read`	Mark one as read
DELETE	`/notifier/notifications/:id`	Clear one notification
GET	`/notifier/config`	Fetch UI config (safe for frontend)
GET	`/notifier/settings`	Get full settings
PUT	`/notifier/settings`	Update settings
DELETE	`/notifier/settings`	Reset settings to defaults
GET	`/notifier/preferences/me`	Get current user's notification prefs
PUT	`/notifier/preferences/me`	Update current user's notification prefs

Query parameters for GET /notifier/notifications:

Param	Default	Description
`page`	`1`	Page number
`pageSize`	`20`	Results per page

Permissions

Two permissions are registered under the Notifier plugin section in Settings → Roles:

plugin::notifier.settings.read — view the settings panel
plugin::notifier.settings.update — save or reset settings

Content types

UID	Collection	Description
`plugin::notifier.notification`	`notifier_notifications`	Notification records
`plugin::notifier.notification-preference`	`notifier_preferences`	Per-user opt-out preferences

Both are hidden from Content Manager and Content-Type Builder by default.