API reference for the @novu/js package
Complete API reference for the Novu JavaScript package
Novu
The Novu client provides methods to interact with notifications, preferences, and real-time events.
Constructor Options
Prop | Type | Default |
---|---|---|
subscriber? | string | Subscriber | - |
subscriberId? | string | - |
useCache? | boolean | - |
socketUrl? | string | - |
apiUrl? | string | - |
subscriberHash? | string | - |
applicationIdentifier? | string | undefined | - |
backendUrl? | string | - |
Usage
Notifications
Methods
list
Fetches a list of notifications based on provided filters.
Prop | Type | Default |
---|---|---|
data? | Record<string, unknown> | - |
seen? | boolean | - |
snoozed? | boolean | - |
archived? | boolean | - |
read? | boolean | - |
tags? | string[] | - |
The response will be of type:
Prop | Type | Default |
---|---|---|
filter? | NotificationFilter | - |
hasMore? | boolean | - |
notifications? | Notification[] | - |
count
Fetches the count of notifications based on filters.
Prop | Type | Default |
---|---|---|
data? | Record<string, unknown> | - |
seen? | boolean | - |
snoozed? | boolean | - |
archived? | boolean | - |
read? | boolean | - |
tags? | string[] | - |
read
Marks a notification as read.
unread
Marks a notification as unread.
seen
Marks a notification as seen.
Seen vs Read: Notifications can be "seen" (automatically tracked when visible) or "read" (explicitly marked by user interaction). The Inbox component automatically marks notifications as seen when they're visible for 1+ seconds using the browser's IntersectionObserver API. This automatic tracking batches requests for performance and works seamlessly with infinite scroll and pagination, while read status requires explicit user action.
Why no unseen
method? Unlike read
/unread
which can be toggled, seen
is designed as a one-way operation. Once a notification has been seen by a user, it remains seen. This reflects the natural user experience where visibility cannot be "undone". Use filtering with seen: false
to get unseen notifications instead.
seenAll
Marks notifications as seen. It can be filtered either by notification IDs, tags, or data.
archive
Archives a notification.
unarchive
Unarchives a notification.
readAll
Marks all notifications as read. Can be filtered by tags.
archiveAll
Archives all notifications. Can be filtered by tags.
archiveAllRead
Archives all read notifications. Can be filtered by tags.
completePrimary
Marks primary action of a notification as completed.
completeSecondary
Marks secondary action of a notification as completed.
revertPrimary
Reverts primary action of a notification to pending.
revertSecondary
Reverts secondary action of a notification to pending.
Notification
Individual notification instances have their own methods for marking as seen, read, archived, etc. These methods are available directly on each notification object.
Methods
seen()
- Marks the notification as seenread()
- Marks the notification as readunread()
- Marks the notification as unreadarchive()
- Archives the notificationunarchive()
- Unarchives the notificationcompletePrimary()
- Marks primary action as completedcompleteSecondary()
- Marks secondary action as completedrevertPrimary()
- Reverts primary action to pendingrevertSecondary()
- Reverts secondary action to pending
Note: The seen()
method is only available on individual notification instances, not on the novu.notifications
object. Use novu.notifications.seenAll()
for bulk operations.
Usage
Preferences
Methods
list
Fetches the subscriber's notification preferences.
The response will be of type:
Prop | Type | Default |
---|---|---|
workflow? | Workflow | - |
overrides? | IPreferenceOverride[] | - |
channels? | ChannelPreference | - |
enabled? | boolean | - |
level? | PreferenceLevel | - |
Events
The Novu client provides real-time event handling through WebSocket connections.
Available Events
notifications.notification_received
: Triggered when a new notification is receivednotifications.unread_count_changed
: Triggered when the unread count changesnotifications.unseen_count_changed
: Triggered when the unseen count changes
Usage
Types
Notification
Prop | Type | Default |
---|---|---|
off? | <Key extends EventNames>(eventName: Key, listener: EventHandler<Events[Key]>) => void | - |
on? | <Key extends EventNames>(eventName: Key, listener: EventHandler<Events[Key]>) => () => void | - |
revertSecondary? | () => Result<Notification> | - |
revertPrimary? | () => Result<Notification> | - |
completeSecondary? | () => Result<Notification> | - |
completePrimary? | () => Result<Notification> | - |
unsnooze? | () => Result<Notification> | - |
snooze? | (snoozeUntil: string) => Result<Notification> | - |
unarchive? | () => Result<Notification> | - |
archive? | () => Result<Notification> | - |
seen? | () => Result<Notification> | - |
unread? | () => Result<Notification> | - |
read? | () => Result<Notification> | - |
workflow? | Workflow | - |
data? | NotificationData | - |
redirect? | Redirect | undefined | - |
tags? | string[] | undefined | - |
channelType? | ChannelType | - |
secondaryAction? | Action | - |
primaryAction? | Action | - |
avatar? | string | - |
archivedAt? | string | null | - |
firstSeenAt? | string | null | - |
readAt? | string | null | - |
createdAt? | string | - |
deliveredAt? | string[] | - |
snoozedUntil? | string | null | - |
isSnoozed? | boolean | - |
isArchived? | boolean | - |
isSeen? | boolean | - |
isRead? | boolean | - |
to? | Subscriber | - |
body? | string | - |
subject? | string | - |
id? | string | - |
Subscriber
Prop | Type | Default |
---|---|---|
timezone? | string | - |
data? | Record<string, unknown> | - |
locale? | string | - |
avatar? | string | - |
phone? | string | - |
email? | string | - |
lastName? | string | - |
firstName? | string | - |
subscriberId? | string | - |
id? | string | - |