Skip to main content
SDK Version

Inbox

The Inbox feature allows your application to provide users with an in-app message center, ensuring that notifications remain accessible even after they are dismissed from the system tray. By implementing an inbox, you can significantly increase user engagement, as messages will always be available directly within your app.

To enable this functionality, include the actito-web/inbox module in your project. This module provides all the APIs necessary to retrieve, open, and manage inbox messages.

Requirements

Before getting started with this module, ensure that the following steps have been completed:

Overview​

The standard implementation uses a device-level inbox, meaning each device maintains its own independent message list — regardless of the authenticated user. This design ensures that every device receives and stores messages consistently, even before a user logs in.

Important

You should not use both the actito-web/inbox and actito-web/user-inbox modules within the same application. Each module provides its own independent implementation of the inbox feature — actito-web/inbox manages messages at the device level, while actito-web/user-inbox manages them at the user level. Using both simultaneously can cause synchronization issues, and unexpected behavior. Choose the module that best fits your use case and integrate only one inbox type per app.

If your application requires an inbox that persists across multiple devices for the same authenticated user, refer to the User Inbox documentation for implementation details.

Fetching Inbox Items​

You can retrieve all messages available in the user’s inbox using the fetchInbox() function. This method returns an object containing the list of inbox items, the total count, and the number of unread messages.

import { fetchInbox } from 'actito-web/inbox'

const { items, count, unread } = await fetchInbox();

You can also customize the query by passing an options object to fetchInbox(). This allows you to control pagination or filter messages retrieved from the server.

const inbox = await fetchInbox({
  since: '',   // (optional) An ISO 8601 date string to fetch messages received after this date.
  skip: 0,     // (optional) The number of records to skip (useful for pagination).
  limit: 100,  // (optional) The maximum number of records to retrieve.
});

Opening Inbox items​

Once you hold a reference to an inbox item, you can open it by invoking the following method:

import { openInboxItem } from 'actito-web/inbox';
import { presentNotification } from 'actito-web/push-ui';

try {
  const notification = await openInboxItem(item);

  // Optionally, present the notification using the managed Push UI
  presentNotification(notification);
} catch (e) {
  // Handle the error
}

Managing Inbox items​

You can manage the inbox contents through a variety of operations provided by the SDK.

Marking messages as read​

To mark a specific message as read:

import { markInboxItemAsRead } from 'actito-web/inbox';

await markInboxItemAsRead(item);

To mark all messages as read:

import { markAllInboxItemsAsRead } from 'actito-web/inbox';

await markAllInboxItemsAsRead();

Removing messages​

To remove a single message from the inbox:

import { removeInboxItem } from 'actito-web/inbox';

await removeInboxItem(item);

To clear all messages from the inbox:

import { clearInbox } from 'actito-web/inbox';

await clearInbox();