> ## Documentation Index
> Fetch the complete documentation index at: https://v0.x-docs.novu.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Headless API Reference

This page contains the complete documentation about the Headless Notification Center package. You can find here the list of all the methods that you can use.

## initializeSession

To use the headless service, you'll need to initialize the session first. This sets the token and starts the socket listener service.

```typescript theme={null}
headlessService.initializeSession({
  listener: (result: FetchResult<ISession>) => {
    console.log(result);
  },
  onSuccess: (session: ISession) => {
    console.log(session);
  },
  onError: (error: unknown) => {
    console.error(error);
  },
});
```

### method args interface

```typescript theme={null}
interface IInitializeSession {
  listener: (result: FetchResult<ISession>) => void;
  onSuccess?: (session: ISession) => void;
  onError?: (error: unknown) => void;
}
```

## fetchOrganization

Fetches the details of the current organization

```typescript theme={null}
headlessService.fetchOrganization({
  listener: (result: FetchResult<IOrganizationEntity>) => {
    console.log(result);
  },
  onSuccess: (organization: IOrganizationEntity) => {
    console.log(organization);
  },
  onError: (error: unknown) => {
    console.error(error);
  },
});
```

### method args interface

```typescript theme={null}
interface IFetchOrganization {
  listener: (result: FetchResult<IOrganizationEntity>) => void;
  onSuccess?: (session: IOrganizationEntity) => void;
  onError?: (error: unknown) => void;
}
```

## fetchUnseenCount

Fetches the count of unseen messages

```typescript theme={null}
headlessService.fetchUnseenCount({
  listener: (result: FetchResult<{ count: number }>) => {
    console.log(result);
  },
  onSuccess: (data: { count: number }) => {
    console.log(data);
  },
  onError: (error: unknown) => {
    console.error(error);
  },
});
```

### method args interface

```typescript theme={null}
interface IFetchUnseenCount {
  listener: (result: FetchResult<{ count: number }>) => void;
  onSuccess?: (data: { count: number }) => void;
  onError?: (error: unknown) => void;
}
```

## fetchUnreadCount

Fetches the count of unread messages

```typescript theme={null}
headlessService.fetchUnreadCount({
  listener: (result: FetchResult<{ count: number }>) => {
    console.log(result);
  },
  onSuccess: (data: { count: number }) => {
    console.log(data);
  },
  onError: (error: unknown) => {
    console.error(error);
  },
});
```

### method args interface

```typescript theme={null}
interface IFetchUnreadCount {
  listener: (result: FetchResult<{ count: number }>) => void;
  onSuccess?: (data: { count: number }) => void;
  onError?: (error: unknown) => void;
}
```

## listenNotificationReceive

Listens to a new notification being added. Can be used to retrieve a new notification in real-time and trigger UI changes.

```typescript theme={null}
headlessService.listenNotificationReceive({
  listener: (message: IMessage) => {
    console.log(JSON.stringify(message));
  },
});
```

### method args interface

```typescript theme={null}
interface IListenNotificationReceive {
  listener: (message: IMessage) => void;
}
```

## listenUnseenCountChange

Listens to the changes of the unseen count. Can be used to get real time count of the unseen messages.

```typescript theme={null}
headlessService.listenUnseenCountChange({
  listener: (unseenCount: number) => {
    console.log(unseenCount);
  },
});
```

### method args interface

```typescript theme={null}
interface IListenUnseenCountChanget {
  listener: (unseenCount: number) => void;
}
```

## listenUnreadCountChange

Listens to the changes of the unread count. Can be used to get real time count of the unread messages.

```typescript theme={null}
headlessService.listenUnreadCountChange({
  listener: (unreadCount: number) => {
    console.log(unreadCount);
  },
});
```

### method args interface

```typescript theme={null}
interface IListenUnreadCountChanget {
  listener: (unreadCount: number) => void;
}
```

## fetchNotifications

Retrieves the list of notifications for the subscriber. Can also be used to get the notifications of a particular tab.

```typescript theme={null}
headlessService.fetchNotifications({
  listener: (result: FetchResult<IPaginatedResponse<IMessage>>) => {
    console.log(result);
  },
  onSuccess: (response: IPaginatedResponse<IMessage>) => {
    console.log(
      response.data,
      response.page,
      response.totalCount,
      response.pageSize
    );
  },
  page: pageNumber,
  query: { 
    feedIdentifier: "feedId", 
    read: false, 
    seen: true, 
    // payload sent while triggering the workflow
    payload: {
      message : "Notification message",
      type: "product",
    } 
  },
  storeId: "storeId",
});
```

### method args interface

```typescript theme={null}
interface IFetchNotifications {
  page?: number;
  storeId?: string;
  query?: IStoreQuery;
  listener: (result: FetchResult<IPaginatedResponse<IMessage>>) => void;
  onSuccess?: (messages: IPaginatedResponse<IMessage>) => void;
  onError?: (error: unknown) => void;
}
```

## fetchUserPreferences

Fetches the user [preferences](/subscribers/preferences)

```typescript theme={null}
headlessService.fetchUserPreferences({
  listener: (result: FetchResult<IUserPreferenceSettings[]>) => {
    console.log(result);
  },
  onSuccess: (settings: IUserPreferenceSettings[]) => {
    console.log(settings);
  },
  onError: (error: unknown) => {
    console.error(error);
  },
});
```

### method args interface

```typescript theme={null}
interface IFetchUserPreferences {
  listener: (result: FetchResult<IUserPreferenceSettings[]>) => void;
  onSuccess?: (settings: IUserPreferenceSettings[]) => void;
  onError?: (error: unknown) => void;
}
```

## updateUserPreferences

Updates the user [preferences](/subscribers/preferences).

```typescript theme={null}
headlessService.updateUserPreferences({
  listener: (
    result: UpdateResult<
      IUserPreferenceSettings,
      unknown,
      IUpdateUserPreferencesVariables
    >
  ) => {
    console.log(result);
  },
  onSuccess: (settings: IUserPreferenceSettings) => {
    console.log(settings);
  },
  onError: (error: unknown) => {
    console.error(error);
  },
  templateId: "templateId",
  channelType: "SMS",
  checked: true,
});
```

### method args interface

```typescript theme={null}
interface IUpdateUserPreferences {
  templateId: IUpdateUserPreferencesVariables["templateId"];
  channelType: IUpdateUserPreferencesVariables["channelType"];
  checked: IUpdateUserPreferencesVariables["checked"];
  listener: (
    result: UpdateResult<
      IUserPreferenceSettings,
      unknown,
      IUpdateUserPreferencesVariables
    >
  ) => void;
  onSuccess?: (settings: IUserPreferenceSettings) => void;
  onError?: (error: unknown) => void;
}
```

## markNotificationsAsRead

Mark a single or multiple notifications as read using the message id.

```typescript theme={null}
headlessService.markNotificationsAsRead({
  listener: (
    result: UpdateResult<IMessage, unknown, { messageId: IMessageId }>
  ) => {
    console.log(result);
  },
  onSuccess: (message: IMessage) => {
    console.log(message);
  },
  onError: (error: unknown) => {
    console.error(error);
  },
  messageId: ["messageOne", "messageTwo"],
});
```

### method args interface

```typescript theme={null}
interface IMarkNotificationsAsRead {
  messageId: IMessageId;
  listener: (
    result: UpdateResult<IMessage, unknown, { messageId: IMessageId }>
  ) => void;
  onSuccess?: (message: IMessage) => void;
  onError?: (error: unknown) => void;
}
```

## markNotificationsAsSeen

Mark a single or multiple notifications as seen using the message id.

```typescript theme={null}
headlessService.markNotificationsAsSeen({
  listener: (
    result: UpdateResult<IMessage, unknown, { messageId: IMessageId }>
  ) => {
    console.log(result);
  },
  onSuccess: (message: IMessage) => {
    console.log(message);
  },
  onError: (error: unknown) => {
    console.error(error);
  },
  messageId: ["messageOne", "messageTwo"],
});
```

### method args interface

```
interface IMarkNotificationsAsSeen {
  messageId: IMessageId;
  listener: (result: UpdateResult<IMessage, unknown, { messageId: IMessageId }>) => void;
  onSuccess?: (message: IMessage) => void;
  onError?: (error: unknown) => void;
}

```

## markNotificationsAs

Mark a single or multiple notifications using the message id.

```typescript theme={null}
headlessService.markNotificationsAs({
  listener: (
    result: UpdateResult<IMessage, unknown, { messageId: IMessageId }>
  ) => {
    console.log(result);
  },
  onSuccess: (message: IMessage) => {
    console.log(message);
  },
  onError: (error: unknown) => {
    console.error(error);
  },
  messageId: ["messageOne", "messageTwo"],
  mark: { seen: true, read: true };
});
```

### method args interface

```typescript theme={null}
interface IMarkNotificationsAs {
  messageId: IMessageId;
  mark: { seen?: boolean; read?: boolean };
  listener: (
    result: UpdateResult<IMessage, unknown, { messageId: IMessageId }>
  ) => void;
  onSuccess?: (message: IMessage) => void;
  onError?: (error: unknown) => void;
}
```

## removeNotification

Removes a single notification using the message id.

```typescript theme={null}
headlessService.removeNotification({
  listener: (
    result: UpdateResult<IMessage, unknown, { messageId: string }>
  ) => {
    console.log(result);
  },
  onSuccess: (message: IMessage) => {
    console.log(message);
  },
  onError: (error: unknown) => {
    console.error(error);
  },
  messageId: "messageOne",
});
```

### method args interface

```typescript theme={null}
interface IRemoveNotification {
  messageId: string;
  listener: (
    result: UpdateResult<IMessage, unknown, { messageId: string }>
  ) => void;
  onSuccess?: (message: IMessage) => void;
  onError?: (error: unknown) => void;
}
```

## removeNotifications

<Note>This method is available from version 0.23.1</Note>

Removes multiple notifications using array of message ids (limit of 100).

```typescript theme={null}
headlessService.removeNotifications({
  listener: (
    result: UpdateResult<void, unknown, { messageIds: string[] }>
  ) => {
    console.log(result);
  },
  onSuccess: (message: IMessage) => {
    console.log(message);
  },
  onError: (error: unknown) => {
    console.error(error);
  },
  messageIds: ["message_id_1", "message_id_2" ],
});
```

### method args interface

```typescript theme={null}
interface IRemoveNotification {
  messageIds: string[];
  listener: (
    result: UpdateResult<void, unknown, { messageIds: string[] }>
  ) => void;
  onSuccess?: (message: IMessage) => void;
  onError?: (error: unknown) => void;
}
```

## removeAllNotifications

Removes all notifications. Can be used to remove all notifications of a feed by passing the `feedId`

```typescript theme={null}
headlessService.removeAllNotifications({
  listener: (result: UpdateResult<void, unknown, undefined>) => {
    console.log(result);
  },
  onSuccess: () => {
    console.log("success");
  },
  onError: (error: unknown) => {
    console.error(error);
  },
  feedId: "feedOne",
});
```

### method args interface

```typescript theme={null}
interface IRemoveAllNotifications {
  feedId?: string;
  listener: (result: UpdateResult<void, unknown, undefined>) => void;
  onSuccess?: () => void;
  onError?: (error: unknown) => void;
}
```

## updateAction

Updates the action button for the notifications.

```typescript theme={null}
headlessService.updateAction({
  listener: (
    result: UpdateResult<IMessage, unknown, IUpdateActionVariables>
  ) => {
    console.log(result);
  },
  onSuccess: (data: IMessage) => {
    console.log(data);
  },
  onError: (error: unknown) => {
    console.error(error);
  },
  messageId: "messageOne",
  actionButtonType: "primary",
  status: "done",
  payload: {
    abc: "def",
  },
});
```

### method args interface

```typescript theme={null}
interface IUpdateAction {
  messageId: IUpdateActionVariables["messageId"];
  actionButtonType: IUpdateActionVariables["actionButtonType"];
  status: IUpdateActionVariables["status"];
  payload?: IUpdateActionVariables["payload"];
  listener: (
    result: UpdateResult<IMessage, unknown, IUpdateActionVariables>
  ) => void;
  onSuccess?: (data: IMessage) => void;
  onError?: (error: unknown) => void;
}
```

## markAllMessagesAsRead

Mark subscriber's all unread messages as read. Can be used to mark all messages as read of a single or multiple feeds by passing the `feedId`

```typescript theme={null}
headlessService.markAllMessagesAsRead({
  listener: (result: UpdateResult<number, unknown, undefined>) => {
    console.log(result);
  },
  onSuccess: (count: number) => {
    console.log(count);
  },
  onError: (error: unknown) => {
    console.error(error);
  },
  feedId: ["feedOne", "feedTwo"],
});
```

### method args interface

```typescript theme={null}
interface IMarkAllMessagesAsRead {
  listener: (result: UpdateResult<number, unknown, undefined>) => void;
  onSuccess?: (count: number) => void;
  onError?: (error: unknown) => void;
  feedId?: IFeedId;
}
```

## markAllMessagesAsSeen

Mark subscriber's all unread messages as seen. Can be used to mark all messages as seen of a single or multiple feeds by passing the `feedId`

```typescript theme={null}
headlessService.markAllMessagesAsSeen({
  listener: (result: UpdateResult<number, unknown, undefined>) => {
    console.log(result);
  },
  onSuccess: (count: number) => {
    console.log(count);
  },
  onError: (error: unknown) => {
    console.error(error);
  },
  feedId: ["feedOne", "feedTwo"],
});
```

### method args interface

```typescript theme={null}
interface IMarkAllMessagesAsSeen {
  listener: (result: UpdateResult<number, unknown, undefined>) => void;
  onSuccess?: (count: number) => void;
  onError?: (error: unknown) => void;
  feedId?: IFeedId;
}
```

## Types and Interfaces

```typescript theme={null}
interface IHeadlessServiceOptions {
  backendUrl?: string;
  socketUrl?: string;
  applicationIdentifier: string;
  subscriberId?: string;
  subscriberHash?: string;
  config?: {
    retry?: number;
    retryDelay?: number;
  };
}

interface ISession {
  token: string;
  profile: ISubscriberJwt;
}

interface ISubscriberJwt {
  _id: string;
  firstName: string;
  lastName: string;
  email: string;
  subscriberId: string;
  organizationId: string;
  environmentId: string;
  aud: "widget_user";
}

interface IUpdateUserPreferencesVariables {
  templateId: string;
  channelType: string;
  checked: boolean;
}

enum ButtonTypeEnum {
  PRIMARY = "primary",
  SECONDARY = "secondary",
  CLICKED = "clicked",
}

enum MessageActionStatusEnum {
  PENDING = "pending",
  DONE = "done",
}

interface IUpdateActionVariables {
  messageId: string;
  actionButtonType: ButtonTypeEnum;
  status: MessageActionStatusEnum;
  payload?: Record<string, unknown>;
}

type FetchResult<T = unknown> = Pick<
  QueryObserverResult<T>,
  "data" | "error" | "status" | "isLoading" | "isFetching" | "isError"
>;

type UpdateResult<
  TData = unknown,
  TError = unknown,
  TVariables = unknown
> = Pick<
  MutationObserverResult<TData, TError, TVariables>,
  "data" | "error" | "status" | "isLoading" | "isError"
>;

type IMessageId = string | string[];
type IFeedId = string | string[];
```

<Tip>
  QueryObserverResult and MutationObserverResult are imported from
  the `@tanstack/query-core` library.
</Tip>