@novu/js | Novu Documentation

Novu

The Novu client provides methods to interact with notifications, preferences, and real-time events.

Constructor Options

Prop	Type	Default
`applicationIdentifier?`	`string`	-
`subscriberId?`	`string`	-
`subscriberHash?`	`string`	-
`backendUrl?`	`string`	-
`apiUrl?`	`string`	-
`socketUrl?`	`string`	-
`useCache?`	`boolean`	-

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
`tags?`	`string[]`	-
`read?`	`boolean`	-
`archived?`	`boolean`	-

const notifications = await novu.notifications.list({
  limit: 30,
  read: false,
  archived: false,
  tags: ['tag1', 'tag2'],
  offset: 0,
});

The response will be of type:

Prop	Type	Default
`notifications?`	`Notification[]`	-
`hasMore?`	`boolean`	-
`filter?`	`NotificationFilter`	-

count

Fetches the count of notifications based on filters.

Prop	Type	Default
`tags?`	`string[]`	-
`read?`	`boolean`	-
`archived?`	`boolean`	-

// Single filter
const count = await novu.notifications.count({
  read: false,
  archived: false,
});

read

Marks a notification as read.

await novu.notifications.read('NOTIFICATION_ID');

unread

Marks a notification as unread.

await novu.notifications.unread('NOTIFICATION_ID');

unarchive

Unarchives a notification.

await novu.notifications.unarchive('NOTIFICATION_ID');

readAll

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

await novu.notifications.readAll({
  tags: ['tag1', 'tag2'],
});

archiveAll

Archives all notifications. Can be filtered by tags.

await novu.notifications.archiveAll({
  tags: ['tag1', 'tag2'],
});

archiveAllRead

Archives all read notifications. Can be filtered by tags.

await novu.notifications.archiveAllRead({
  tags: ['tag1', 'tag2'],
});

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

Preferences

Methods

list

Fetches the subscriber's notification preferences.

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

The response will be of type:

Prop	Type	Default
`level?`	`PreferenceLevel`	-
`enabled?`	`boolean`	-
`channels?`	`ChannelPreference`	-
`overrides?`	`IPreferenceOverride[]`	-
`workflow?`	`Workflow`	-

update

Updates channel preferences for a specific workflow or globally.

Prop	Type	Default
`email?`	`boolean`	-
`sms?`	`boolean`	-
`in_app?`	`boolean`	-
`chat?`	`boolean`	-
`push?`	`boolean`	-

await novu.preferences.update({
  workflowId: 'workflow_id',
  channelPreferences: {
    email: false,
    sms: false,
  },
});

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

Usage

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

Types

Notification

Prop	Type	Default
`id?`	`string`	-
`subject?`	`string`	-
`body?`	`string`	-
`to?`	`Subscriber`	-
`isRead?`	`boolean`	-
`isArchived?`	`boolean`	-
`createdAt?`	`string`	-
`readAt?`	`string`	-
`archivedAt?`	`string`	-
`avatar?`	`string`	-
`primaryAction?`	`Action`	-
`secondaryAction?`	`Action`	-
`channelType?`	`ChannelType`	-
`tags?`	`string[]`	-
`redirect?`	`Redirect`	-
`data?`	`Record<string, unknown>`	-
`read?`	`() => Result<Notification, NovuError>`	-
`unread?`	`() => Result<Notification, NovuError>`	-
`archive?`	`() => Result<Notification, NovuError>`	-
`unarchive?`	`() => Result<Notification, NovuError>`	-
`completePrimary?`	`() => Result<Notification, NovuError>`	-
`completeSecondary?`	`() => Result<Notification, NovuError>`	-
`revertPrimary?`	`() => Result<Notification, NovuError>`	-
`revertSecondary?`	`() => Result<Notification, NovuError>`	-
`on?`	`<Key extends EventNames>(eventName: Key, listener: EventHandler<Events[Key]>) => () => void`	-
`off?`	`<Key extends EventNames>(eventName: Key, listener: EventHandler<Events[Key]>) => void`	-

Action

Prop	Type	Default
`label?`	`string`	-
`isCompleted?`	`boolean`	-
`redirect?`	`Redirect`	-

NotificationButton

Prop	Type	Default
`PRIMARY?`	`NotificationButton.PRIMARY`	-
`SECONDARY?`	`NotificationButton.SECONDARY`	-

Subscriber

Prop	Type	Default
`id?`	`string`	-
`firstName?`	`string`	-
`lastName?`	`string`	-
`avatar?`	`string`	-
`subscriberId?`	`string`	-

API reference for the @novu/js package

Novu

Constructor Options

Usage

Notifications

Methods

list

count

read

unread

archive

unarchive

readAll

archiveAll

archiveAllRead

completePrimary

completeSecondary

revertPrimary

revertSecondary

Preferences

Methods

list

update

Events

Available Events

Usage

Types

Notification

Action

NotificationButton

Subscriber

On this page