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.

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

{
  "dependencies": {
    "capacitor-actito-inbox": "^5.0.0"
  }
}

Requirements

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

• You have successfully completed the Getting Started guide

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-inbox and actito-user-inbox modules within the same application. Each module provides its own independent implementation of the inbox feature — actito-inbox manages messages at the device level, while actito-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.

Listening to Inbox changes

The inbox can be observed through the Actito Inbox API, allowing your UI to automatically reflect changes as messages arrive, are read, or removed.

Example — observing inbox items:

ActitoInbox.onInboxUpdated((items) => {
  // Do something with the items.
});

Similarly, you can listen for updates to the number of unread messages:

ActitoInbox.onBadgeUpdated((badge) => {
  // Do something with the badge.
});

For synchronous access, you can retrieve the current state directly:

// Retrieve the list of inbox items
const items = await ActitoInbox.getItems();

// Retrieve the current unread badge count
const badge = await ActitoInbox.getBadge();

Opening Inbox items

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

const item: ActitoInboxItem;

try {
  const notification = await ActitoInbox.open(item);
  await ActitoPushUI.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 a read

To mark a specific message as read:

const item: ActitoInboxItem;

try {
  await ActitoInbox.markAsRead(item);
} catch (e) {
  // Handle the error
}

To mark all messages as read:

try {
  await ActitoInbox.markAllAsRead();
} catch (e) {
  // Handle error
}

Removing messages

To remove a single message from the inbox:

const item: ActitoInboxItem;

try {
  await ActitoInbox.remove(item);
} catch (e) {
  // Handle error
}

To clear all messages from the inbox:

try {
  await ActitoInbox.clear();
} catch (e) {
  // Handle error
}