Headless Inbox API Reference

Novu

Novu is the primary class used to interact with the Novu API client, enabling you to fetch and manage notifications and preferences within your custom Inbox implementation.

Constructor options

applicationIdentifier · string · required

applicationIdentifier is a unique identifier for the application. This is is public credential that is used to authenticate the application with the Novu API. applicationIdentifier can be copied from API Keys page.

subscriberId · string · required

subscriberId is a unique identifier for the subscriber. Read more about subscribers.

subscriberHash · string

subscriberHash is a unique identifier for the subscriber. It is used for HMAC encryption. Read more about HMAC Encryption.

backendUrl · string · default: "https://api.novu.co"

Use https://eu.api.novu.co value for EU region.

socketUrl · string · default: "https://ws.novu.co"

Use https://eu.ws.novu.co value for EU region.

useCache · boolean

The field is used to enable/disable the cache for the notifications and preferences. By default, the cache is enabled.

Usage

US

import { Novu } from "@novu/js";

const novu = new Novu({
  subscriberId: "SUBSCRIBER_ID",
  applicationIdentifier: "APPLICATION_IDENTIFIER",
});

Modules interface

• Notifications
• Preferences

Notifications

Methods

• list
• count
• read
• unread
• archive
• unarchive
• readAll
• archiveAll
• archiveAllRead
• completePrimary
• completeSecondary
• revertPrimary
• revertSecondary

Notification Interface

type Subscriber = {
  id: string;
  firstName?: string;
  lastName?: string;
  avatar?: string;
  subscriberId: string;
};

enum ChannelType {
  IN_APP = "in_app",
  EMAIL = "email",
  SMS = "sms",
  CHAT = "chat",
  PUSH = "push"
}

type Redirect = {
  url: string;
  target?: '_self' | '_blank' | '_parent' | '_top' | '_unfencedTop';
};

type Action = {
  label: string;
  isCompleted: boolean;
  redirect?: Redirect;
};

interface Notification = {
  id: string;
  subject?: string;
  body: string;
  to: Subscriber;
  isRead: boolean;
  isArchived: boolean;
  createdAt: string;
  readAt?: string | null;
  archivedAt?: string | null;
  avatar?: string;
  primaryAction?: Action;
  secondaryAction?: Action;
  channelType: ChannelType;
  tags?: string[];
  data?: Record<string, unknown>;
  redirect?: Redirect;
};

list

Method to fetch the list of notifications based on the provided filters. By default the response is cached internally and stored by provided filters as a key. The cache will be updated automatically with the subsequent response if the filters didn’t change. All cached responses will be merged into a single list and returned as the result. You can disable this behaviour and the cache by setting the useCache parameter to false in the Novu constructor options.

Params

tags · string[]

Workflow tags can be used to filter notifications where at least one specified tag matches. Read more about how can you define workflow tags.

read · boolean

Filter notifications based on their read status. If not provided, all read/unread notifications will be returned.

archived · boolean

Filter notifications based on their archived status. Archived notifications are also read at the same time. If not provided, all archived/unarchived notifications will be returned.

limit · number

Limit the number of notifications to be fetched. It can take any number between 1 and 100. Default is 10.

after · string

after can be used to fetch the next set of notifications after a specific notification. It can take notification.id as value.

offset · offset

Field value can be used to skip the first n notifications. It can be used in conjunction with limit to paginate the notifications.

Returns

The returned object contains the data and error fields.

Hide properties

data · ListNotificationsResponse

The data object contains the list of notifications and other metadata.

Show properties

notifications · Notification[]

List of notifications. Read more about Notification Interface.

hasMore · boolean

Indicates if there are more notifications available.

filter · NotificationFilter

Filters used to fetch the notifications.

error · NovuError

Error object if the request fails.

Usage

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

count

Method to fetch the count of read, unread, archived and unarchived notifications grouped by tags. You can also pass multiple filters to fetch the different notifications counts.

Params

tags · string[]

Workflow tags can be used to count notifications where at least one specified tag matches. Read more about how can you define workflow tags.

read · boolean

Count notifications based on their read status. If not provided, all read/unread notifications will be counted.

archived · boolean

Count notifications based on their archived status. Archived notifications are also read at the same time. If not provided, all archived/unarchived notifications will be counted.

filters · Filter[]

Multiple filters can be used to count notifications. Each filter can have different tags, read and archived status.

Returns

The returned object contains the data and error fields.

Single

Hide properties

data · FilterCountResponse

The data object contains the count of notifications and other metadata.

Show properties

count · number

List of notifications. Read more about Notification class.

filter · NotificationFilter

Filters used to count the notifications.

error · NovuError

Error object if the request fails.

Usage

const count = await novu.notifications.count({
  read: true,
  archived: false,
  tags: ['tag1', 'tag2'],
});
// OR
const multipleCounts = await novu.notifications.count([
  {
    read: true,
    archived: false,
    tags: ['tag1', 'tag2'],
  },
  {
    read: false,
    archived: false,
    tags: ['tag3', 'tag4'],
  },
]);

read

Method marks a notification as read.

Params

notificationId · string

Notification ID is a unique identifier for the notification. It can be taken from the notification object.

notification · object

Notification object represents the message sent to the subscriber.

Usage

const readNotification = await novu.notifications.read({
  notificationId: 'notification.id',
});
// OR
const readNotification = await novu.notifications.read({
  notification,
});

unread

Method marks a notification as unread.

Params

notificationId · string

Notification ID is a unique identifier for the notification. It can be taken from the notification object.

notification · object

Notification object represents the message sent to the subscriber.

Usage

const unreadNotification = await novu.notifications.unread({
  notificationId: 'notification.id',
});
// OR
const unreadNotification = await novu.notifications.unread({
  notification,
});

archive

Method marks a notification as archived.

Params

notificationId · string

Notification ID is a unique identifier for the notification. It can be taken from the notification object.

notification · object

Notification object represents the message sent to the subscriber.

Usage

const archivedNotification = await novu.notifications.archive({
  notificationId: 'notification.id',
});
// OR
const archivedNotification = await novu.notifications.archive({
  notification,
});

unarchive

Method marks a notification as unarchived.

Params

notificationId · string

Notification ID is a unique identifier for the notification. It can be taken from the notification object.

notification · object

Notification object represents the message sent to the subscriber.

Usage

const unarchivedNotification = await novu.notifications.unarchive({
  notificationId: 'notification.id',
});
// OR
const unarchivedNotification = await novu.notifications.unarchive({
  notification,
});

readAll

Method marks all notifications as read. Notifications can be filtered by tags.

Params

tags · string[]

Workflow tags can be used to filter notifications, and organize them into different groups. Read more about how can you define workflow tags.

Usage

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

archiveAll

Method marks all notifications as archived. Notifications can be filtered by tags.

Params

tags · string[]

Workflow tags can be used to filter notifications, and organize them into different groups. Read more about how can you define workflow tags.

Usage

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

archiveAllRead

Method marks all read notifications as archived. Notifications can be filtered by tags.

Params

tags · string[]

Workflow tags can be used to filter notifications, and organize them into different groups. Read more about how can you define workflow tags.

Usage

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

completePrimary

Method marks primary action of a notification as completed. It changes the isCompleted field of primaryAction to done from pending.

Params

notificationId · string

Usage

await novu.notifications.completePrimary({
  notificationId: "notification.id",
});

completeSecondary

Method marks secondary action of a notification as completed. It changes the isCompleted field of primaryAction to done from pending.

Params

notificationId · string

Usage

await novu.notifications.completeSecondary({
  notificationId: "notification.id",
});

revertPrimary

Method marks primary action of a notification as pending. It changes the isCompleted field of primaryAction to pending from done.

Params

notificationId · string

Usage

await novu.notifications.revertPrimary({
  notificationId: "notification.id",
});

revertSecondary

Method marks secondary action of a notification as pending. It changes the isCompleted field of secondaryAction to pending from done.

Params

notificationId · string

Usage

await novu.notifications.revertSecondary({
  notificationId: "notification.id",
});

Preferences

Methods

• list

Preference Interface

type Workflow = {
  id: string;
  identifier: string;
  name: string;
  critical: boolean;
  tags?: string[];
};

type ChannelPreference = {
  email?: boolean;
  sms?: boolean;
  in_app?: boolean;
  chat?: boolean;
  push?: boolean;
};

enum PreferenceLevel {
  GLOBAL = 'global',
  TEMPLATE = 'template',
}

interface Preference {
  enabled: boolean;
  workflow?: Workflow;
  channels: ChannelPreference;
  level: PreferenceLevel;
}

list

Method fetch the global and workflows channel preferences of the subscriber.

Usage

await novu.preferences.list();

Preference

Methods

• update

update

Update the global or per workflow channel preferences of the subscriber.

If workflowId is provided, it updates the channel preferences of the specific workflow. Otherwise, it updates the global channel preferences.

Params

workflowId · string

channelPreferences · ChannelPreference

ChannelPreference

type ChannelPreference = {
  email?: boolean;
  sms?: boolean;
  in_app?: boolean;
  chat?: boolean;
  push?: boolean;
};

Usage

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

Events

Usage

novu.on('notifications.notification_received', (data) => {
  console.log('new notification =>', data);
});

novu.on('notifications.unread_count_changed', (data) => {
  console.log('new unread notifications count =>', data);
});