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 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 is a unique identifier for the subscriber. Read more about
subscribers.
subscriberHash is a unique identifier for the subscriber. It is used for
HMAC encryption. Read more about HMAC
Encryption.
Use https://eu.api.novu.co value for EU region.
Use https://eu.ws.novu.co value for EU region.
The field is used to enable/disable the cache for the notifications and preferences. By default, the cache is enabled.
Usage
import { Novu } from "@novu/js";
const novu = new Novu({
subscriberId: "SUBSCRIBER_ID",
applicationIdentifier: "APPLICATION_IDENTIFIER",
});
Modules interface
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
Workflow tags can be used to filter notifications where at least one specified tag matches. Read more about how can you define workflow tags.
Filter notifications based on their read status. If not provided, all read/unread notifications will be returned.
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 the number of notifications to be fetched. It can take any number between 1 and 100. Default is 10.
after can be used to fetch the next set of notifications after a specific notification. It can take notification.id as value.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.
The data object contains the list of notifications and other metadata.
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
Workflow tags can be used to count notifications where at least one specified tag matches. Read more about how can you define workflow tags.
Count notifications based on their read status. If not provided, all read/unread notifications will be counted.
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.
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.
The data object contains the count of notifications and other metadata.
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
Notification ID is a unique identifier for the notification. It can be taken from the 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
Notification ID is a unique identifier for the notification. It can be taken from the 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
Notification ID is a unique identifier for the notification. It can be taken from the 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
Notification ID is a unique identifier for the notification. It can be taken from the 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
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
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
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
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
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
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
Usage
await novu.notifications.revertSecondary({
notificationId: "notification.id",
});
Preferences
Methods
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
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);
});
Was this page helpful?