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
• EU
• HMAC Encryption

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
• Multiple

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
• update

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();

update

Method updates the channel preferences of the subscriber. It updates the channel preferences of the subscriber for the specific workflow if workflowId is provided. If workflowId is not provided, it updates the global channel preferences of the subscriber. Multiple channels can be updated at once.

Params

workflowId

string

channelPreferences

ChannelPreference

ChannelPreference

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

Usage

await novu.preferences.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);
});