Skip to main content
The notifications plugin tells people when something needs them. It adds a bell to the admin header with the number of unread notifications, an inbox at /admin/notifications, and notify() to send one from any hook, endpoint or job. With the comments plugin, a new @mention notifies the person mentioned. Delivery is in-app only. The bell’s count is read again on every page change; it doesn’t update on its own while a page stays open.

Installation

Configuration

Notifications go to users of the app’s auth collection. With several auth collections, set admin.user.

Sending a notification

Call notify() with the req of the hook, endpoint or job you’re in, so the notification is saved in the same transaction: if the work fails and rolls back, nobody is told about it.
Any field you add to the collection with overrides.fields can be passed too, and is stored. notify() checks no access: your code decides who to tell. Only send people things they may see.

Mentions in comments

With both plugins installed, a comment notifies each user it newly mentions, once, with the comment’s first 140 characters, a link to the record, the author as actor and kind: 'mention'. Editing a comment notifies only the users the edit adds. Nobody is notified for mentioning themselves, and a user who can’t read the record isn’t notified, so the excerpt never reaches someone who couldn’t open it. The two plugins don’t depend on each other: either works alone.

Bell and inbox

The bell shows the signed-in user’s unread count, up to 99+, and links to the inbox. It refreshes on each page change. Set bell: false to leave it out and put your own entry point anywhere. The inbox lists the user’s notifications, newest first, 50 at a time with Load more. Unread ones are bold with a dot. All and Unread switch the list, and Mark all read marks every unread one read. Opening one marks it read and follows its link. Each control is a URL (?filter=unread, ?limit=100).

Build your own

Everything the inbox uses is public, so you can build a different experience on the same data:
  • Components: NotificationsBell from @frogbotai/plugin-notifications/rsc, and BellLink and Inbox from @frogbotai/plugin-notifications/client. Render Inbox in your own view or popover with your own query.
  • REST: each user reads and updates only their own rows, so GET /api/notifications?where[kind][equals]=mention is a “Mentioned” view, and PATCH /api/notifications?where[readAt][exists]=false marks all read.
  • Fields: add your own with overrides.fields and pass them to notify(). For example, an archive:

The notifications collection

Only readAt, and fields you add, can be changed after create. Deleting a user deletes their notifications.

Access

  • Read, update and delete: the user’s own notifications only.
  • Create: nobody through the API. Use notify().
Change them with overrides.access.

Options