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

PropTypeDefault
subscriber?
string | Subscriber
-
subscriberId?
string
-
useCache?
boolean
-
socketUrl?
string
-
apiUrl?
string
-
subscriberHash?
string
-
applicationIdentifier?
string | undefined
-
backendUrl?
string
-

Usage

import { Novu } from "@novu/js";
 
const novu = new Novu({
  subscriberId: "SUBSCRIBER_ID",
  applicationIdentifier: "APPLICATION_IDENTIFIER",
});

Notifications

Methods

list

Fetches a list of notifications based on provided filters.

PropTypeDefault
data?
Record<string, unknown>
-
seen?
boolean
-
snoozed?
boolean
-
archived?
boolean
-
read?
boolean
-
tags?
string[]
-
const notifications = await novu.notifications.list({
  limit: 30,
  read: false,
  seen: false,
  archived: false,
  tags: ['tag1', 'tag2'],
  // data attributes
  data: {
    type: 'login',
  },
  offset: 0,
});

The response will be of type:

PropTypeDefault
filter?
NotificationFilter
-
hasMore?
boolean
-
notifications?
Notification[]
-

count

Fetches the count of notifications based on filters.

PropTypeDefault
data?
Record<string, unknown>
-
seen?
boolean
-
snoozed?
boolean
-
archived?
boolean
-
read?
boolean
-
tags?
string[]
-
// Single filter
const count = await novu.notifications.count({
  read: false,
  seen: false,
  archived: false,
   // data attributes
  data: {
    type: 'login',
  },
});

read

Marks a notification as read.

await novu.notifications.read({ notificationId: 'NOTIFICATION_ID' });

unread

Marks a notification as unread.

await novu.notifications.unread({ notificationId: 'NOTIFICATION_ID' });

seen

Marks a notification as seen.

await novu.notifications.seen({ notificationId: 'NOTIFICATION_ID' });

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.

// Mark specific notifications as seen
await novu.notifications.seenAll({
  notificationIds: ['NOTIFICATION_ID_1', 'NOTIFICATION_ID_2']
});
 
// Mark notifications by tags as seen
await novu.notifications.seenAll({
  tags: ['tag1', 'tag2']
});
 
// Mark notifications by data as seen
await novu.notifications.seenAll({
  data: { type: 'login' }
});
 
// Mark all notifications as seen (no filters)
await novu.notifications.seenAll();

archive

Archives a notification.

await novu.notifications.archive({ notificationId: 'NOTIFICATION_ID' });

unarchive

Unarchives a notification.

await novu.notifications.unarchive({ notificationId: 'NOTIFICATION_ID' });

readAll

Marks all notifications as read. Can be filtered by tags.

await novu.notifications.readAll({
  tags: ['tag1', 'tag2'],
  // data attributes
  data: {
    type: 'login',
  },
});

archiveAll

Archives all notifications. Can be filtered by tags.

await novu.notifications.archiveAll({
  tags: ['tag1', 'tag2'],
  // data attributes
  data: {
    type: 'login',
  },
});

archiveAllRead

Archives all read notifications. Can be filtered by tags.

await novu.notifications.archiveAllRead({
  tags: ['tag1', 'tag2'],
  // data attributes
  data: {
    type: 'login',
  },
});

completePrimary

Marks primary action of a notification as completed.

await novu.notifications.completePrimary({ notificationId: 'NOTIFICATION_ID' });

completeSecondary

Marks secondary action of a notification as completed.

await novu.notifications.completeSecondary({ notificationId: 'NOTIFICATION_ID' });

revertPrimary

Reverts primary action of a notification to pending.

await novu.notifications.revertPrimary({ notificationId: 'NOTIFICATION_ID' });

revertSecondary

Reverts secondary action of a notification to pending.

await novu.notifications.revertSecondary({ notificationId: 'NOTIFICATION_ID' });

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 seen
  • read() - Marks the notification as read
  • unread() - Marks the notification as unread
  • archive() - Archives the notification
  • unarchive() - Unarchives the notification
  • completePrimary() - Marks primary action as completed
  • completeSecondary() - Marks secondary action as completed
  • revertPrimary() - Reverts primary action to pending
  • revertSecondary() - 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

// Get notifications
const { data: notifications } = await novu.notifications.list();
 
// Mark a specific notification as seen using the instance method
await notifications[0].seen();
 
// Mark as read using the instance method
await notifications[0].read();
 
// Archive using the instance method
await notifications[0].archive();

Preferences

Methods

list

Fetches the subscriber's notification preferences.

const preferences = await novu.preferences.list();

The response will be of type:

PropTypeDefault
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 received
  • notifications.unread_count_changed: Triggered when the unread count changes
  • notifications.unseen_count_changed: Triggered when the unseen count changes

Usage

novu.on('notifications.notification_received', (data) => {
  console.log('New notification:', data);
});
 
novu.on('notifications.unread_count_changed', (data) => {
  console.log('Unread count:', data);
});
 
novu.on('notifications.unseen_count_changed', (data) => {
  console.log('Unseen count:', data);
});

Types

Notification

PropTypeDefault
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

PropTypeDefault
timezone?
string
-
data?
Record<string, unknown>
-
locale?
string
-
avatar?
string
-
phone?
string
-
email?
string
-
lastName?
string
-
firstName?
string
-
subscriberId?
string
-
id?
string
-

On this page

Edit this page on GitHub