@novu/js | Novu Documentation

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`	-
`context?`	`Partial<Record<string, ContextValue>>`	-
`defaultSchedule?`	`DefaultSchedule`	-
`useCache?`	`boolean`	-
`socketUrl?`	`string`	-
`apiUrl?`	`string`	-
`contextHash?`	`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.

Prop	Type	Default
`severity?`	`SeverityLevelEnum \| SeverityLevelEnum[]`	-
`data?`	`Record<string, unknown>`	-
`seen?`	`boolean`	-
`snoozed?`	`boolean`	-
`archived?`	`boolean`	-
`read?`	`boolean`	-
`tags?`	`string[]`	-

import { SeverityLevelEnum } from '@novu/js';
 
const notifications = await novu.notifications.list({
  limit: 30,
  read: false,
  seen: false,
  archived: false,
  tags: ['tag1', 'tag2'],
  severity: SeverityLevelEnum.HIGH,
  // data attributes
  data: {
    type: 'login',
  },
  offset: 0,
});

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
`severity?`	`SeverityLevelEnum \| SeverityLevelEnum[]`	-
`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,
  severity: SeverityLevelEnum.HIGH,
   // 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();

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',
  },
});

deleteAll

Deletes multiple notifications. Can be filtered by tags or data attributes.

// Delete specific notifications by tags
await novu.notifications.deleteAll({
  tags: ['tag1', 'tag2'],
});
 
// Delete notifications by data attributes
await novu.notifications.deleteAll({
  data: { type: 'login' },
});
 
// Delete all notifications (no filters)
await novu.notifications.deleteAll();

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
delete() - Deletes 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();
 
// Delete using the instance method
await notifications[0].delete();

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

The response will be of type:

Prop	Type	Default
`schedule?`	`{ isEnabled: boolean; weeklySchedule?: WeeklySchedule \| undefined; }`	-
`workflow?`	`Workflow`	-
`overrides?`	`IPreferenceOverride[]`	-
`channels?`	`ChannelPreference`	-
`enabled?`	`boolean`	-
`level?`	`PreferenceLevel`	-

Schedule

The preferences.schedule submodule lets you fetch and update a subscriber’s delivery schedule.

get

Fetches the subscriber’s schedule.

const novu = new Novu(...);
 
const { data: { schedule } } = await novu.preferences.schedule.get();

update

Updates the subscriber’s schedule. You can update the entire weekly schedule or only specific days.

const novu = new Novu(...);
 
// Update schedule via preferences
const { data: { schedule } } = await novu.preferences.schedule.update({
  weeklySchedule: {
    monday: {
      isEnabled: true,
      hours: [{ start: '09:00 AM', end: '05:00 PM' }],
    },
  },
});
 
// Or update directly from a Schedule instance
const { data: { schedule: updatedSchedule } } =
  await schedule.update({ isEnabled: false });

Schedule Class

A Schedule instance is returned when fetching or updating a schedule.

Prop	Type	Default
`update?`	`(args: UpdateScheduleArgs) => Result<Schedule>`	-
`weeklySchedule?`	`WeeklySchedule \| undefined`	-
`isEnabled?`	`boolean \| undefined`	-

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
preferences.schedule.get.pending: Triggered when fetching a schedule starts
preferences.schedule.get.resolved: Triggered when fetching a schedule succeeds
preferences.schedule.update.pending: Triggered when updating a schedule starts
preferences.schedule.update.resolved: Triggered when updating a schedule succeeds

Usage

 
novu.on('session.initialize.resolved', ({ data }: { data: Session }) => {
  console.log(data.unreadCount.total);
  console.log(data.unreadCount.severity[SeverityLevelEnum.HIGH]);
});
 
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);
});
 
novu.on('preferences.schedule.update.resolved', ({ data }) => {
  console.log('Schedule updated:', data.schedule);
});

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>`	-
`delete?`	`() => Result<void>`	-
`unarchive?`	`() => Result<Notification>`	-
`archive?`	`() => Result<Notification>`	-
`seen?`	`() => Result<Notification>`	-
`unread?`	`() => Result<Notification>`	-
`read?`	`() => Result<Notification>`	-
`severity?`	`SeverityLevelEnum`	-
`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`	-
`transactionId?`	`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`	-

API reference for the @novu/js package

Novu

Constructor Options

Usage

Notifications

Methods

list

count

read

unread

seen

seenAll

archive

unarchive

readAll

archiveAll

archiveAllRead

deleteAll

completePrimary

completeSecondary

revertPrimary

revertSecondary

Notification

Methods

Usage

Preferences

Methods

list

Schedule

get

update

Schedule Class

Events

Available Events

Usage

Types

Notification

Subscriber

On this page