@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. You can filter them by notification IDs, tags, or data attributes.

// 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. You can filter them by tags.

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

archiveAll

Archives all notifications. You can filter them by tags.

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

archiveAllRead

Archives all read notifications. You can filter them by tags.

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

delete

Deletes a single notification permanently.

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

deleteAll

Deletes multiple notifications permanently. You can filter them 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();

snooze

Snoozes a notification for a specified duration. Here snoozeUntil is ISO 8601 formatted string timestamp, representing the date and time the notification is un-snoozed, it should be a future date and time.

await novu.notifications.snooze({ notificationId: 'NOTIFICATION_ID', snoozeUntil: '2025-01-01T00:00:00.000Z' });

unsnooze

Unsnoozes a notification.

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

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
snooze() - Snoozes the notification
unsnooze() - Unsnoozes 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

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();
 
// Snooze using the instance method
await notifications[0].snooze('2025-01-01T00:00:00.000Z');
 
// Unsnooze using the instance method
await notifications[0].unsnooze();
 
// Delete using the instance method
await notifications[0].delete();

Preferences

Methods

list

Fetches the subscriber's notification preferences.

const { data: preferences } = await novu.preferences.list();

update

update method is available with each preference object.

const { data: preferences } = await novu.preferences.list();
 
// Update a single preference
 
await preferences[0].update({ channels: { email: false, sms: true } });

The response will be of type:

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

bulkUpdate

Updates multiple workflow's channel preferences at once.

await novu.preferences.bulkUpdate([
  { workflowId: 'workflow_id', channels: { email: false, sms: true } },
  { workflowId: 'workflow_id_2', channels: { email: true, sms: false, in_app: true } },
]);

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.
subscriptions.list.pending: Triggered when loading subscriptions starts.
subscriptions.list.resolved: Triggered when subscriptions are loaded.
subscriptions.get.pending: Triggered when fetching a subscription starts.
subscriptions.get.resolved: Triggered when a specific subscription is fetched.
subscriptions.create.pending: Triggered when creating a subscription starts.
subscriptions.create.resolved: Triggered when a subscription is created.
subscriptions.update.pending: Triggered when updating a subscription starts.
subscriptions.update.resolved: Triggered when a subscription is updated.
subscriptions.delete.pending: Triggered when deleting a subscription start.
subscriptions.delete.resolved: Triggered when a subscription is deleted.

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);
});
 
novu.on('subscriptions.create.resolved', ({ data: subscription }) => {
  console.log('New subscription created:', subscription.identifier);
});
 
novu.on('subscriptions.list.resolved', ({ data: subscriptions }) => {
  console.log('Loaded subscriptions:', subscriptions.length);
});

Subscriptions

The Subscriptions module lets you manage a subscriber’s subscriptions to topics. A subscription represents a subscriber’s opt-in to a topic and defines which workflows within that topic they receive notifications from.

It supports creating conditional subscriptions where users only receive notifications if specific criteria (payload filters) are met.

Manage subscriptions at two levels:

Module-level methods on novu.subscriptions
Instance-level methods on a TopicSubscription object

Methods

List

Fetches all subscriptions for a specific topic.

Prop	Type	Default
`topicKey?`	`string`	-

const { data: subscriptions } = await novu.subscriptions.list({
  topicKey: 'product-updates'
});

The response items are TopicSubscription instances.

get

Fetch a single subscription by topic and identifier.

Prop	Type	Default
`identifier?`	`string`	-
`topicKey?`	`string`	-

const { data: subscription } = await novu.subscriptions.get({
  topicKey: 'product-updates',
  identifier: 'user-product-alert'
});

create

Create a new subscription to a topic. You can pass a list of preferences to filter specific workflows or tags.

Prop	Type	Default
`preferences?`	`NonEmptyArray<PreferenceFilter>`	-
`name?`	`string`	-
`identifier?`	`string`	-
`topicName?`	`string`	-
`topicKey?`	`string`	-

const { data: subscription } = await novu.subscriptions.create({
  topicKey: 'product-updates',
  identifier: 'user-product-alert',
  preferences: [
    {
      // Simple workflow toggle
      workflowId: 'issue-created',
      enabled: true
    },
    {
      // Conditional filter
      workflowId: 'price-alert',
      condition: {
        field: 'price',
        operation: 'below',
        value: 100
      }
    }
  ]
});

update

Updates an existing subscription.

Prop	Type	Default
`preferences?`	`NonEmptyArray<PreferenceFilter>`	-
`name?`	`string`	-

const { data: subscription } = await novu.subscriptions.update({
  topicKey: 'product-updates',
  subscriptionId: 'subscription-id-123',
  preferences: [...]
});

delete

Delete a subscription by topic and subscription ID.

await novu.subscriptions.delete({
  topicKey: 'product-updates',
  subscriptionId: 'product-updates-subscription',
});

TopicSubscription

A TopicSubscription instance represents a single subscription and provides methods for updating or deleting it, as well as managing its preferences.

Prop	Type	Default
`delete?`	`() => Result<void>`	-
`bulkUpdatePreferences?`	`{ (args: BaseSubscriptionPreferenceArgs[]): Result<SubscriptionPreference[]>; (args: InstanceSubscriptionPreferenceArgs[]): Result<...>; }`	-
`updatePreference?`	`{ (args: BaseSubscriptionPreferenceArgs): Result<SubscriptionPreference>; (args: InstanceSubscriptionPreferenceArgs): Result<...>; }`	-
`update?`	`{ (args: BaseUpdateSubscriptionArgs): Result<TopicSubscription>; (args: InstanceUpdateSubscriptionArgs): Result<...>; }`	-
`preferences?`	`SubscriptionPreference[]`	-
`topicKey?`	`string`	-
`identifier?`	`string`	-
`id?`	`string`	-

Update a subscription

Update subscription metadata or replace its preferences list. Use this method when updating the subscription as a whole. For granular preference updates, use preference-level methods instead.

const { data: subscription } =
  await novu.subscriptions.get({
    topicKey: 'product-updates',
    identifier: 'product-updates-subscription',
  });
 
await subscription.update({
  preferences: [
    {
      workflowId: 'workflow-identifier',
      enabled: true,
    },
  ],
});

Update SubscriptionPreference

Each subscription contains a list of SubscriptionPreference objects that you can update individually.

Prop	Type	Default
`update?`	`(args: { value: RulesLogic; }) => Result<SubscriptionPreference>`	-
`condition?`	`RulesLogic`	-
`enabled?`	`boolean`	-
`workflow?`	`Workflow`	-
`subscriptionId?`	`string`	-

subscription.preferences.map((preference) => {
  const onChange = (value: boolean) => {
    preference.update({ value });
  };
 
  return <Checkbox onChange={onChange} />;
});

Delete a subscription (instance method)

await subscription.delete();

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

On this page