User Inbox

The User Inbox feature allows your application to provide authenticated users with a personalized in-app message center, ensuring that notifications remain accessible even after they are dismissed from the system tray. By implementing a user-level inbox, you can significantly increase engagement by keeping all messages synchronized across multiple devices for the same user.

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

Requirements

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

• You have successfully completed the Getting Started guide.
• You have implemented user authentication in your app and assigned a userId through the API-level user registration process.

Overview

The User Inbox is tied to the authenticated user, rather than the device. This design ensures that all messages are synchronized across any devices where the same user is logged in.

The User Inbox must be retrieved from the Actito REST API by your backend. Because it contains user-specific data, access to the user inbox requires a server-side integration capable of performing authenticated requests using your Master Secret.

Your backend should handle the user’s authentication, securely query the User Inbox API endpoints, and expose the results to your app through your own protected API layer.

For details on the available endpoints and expected payloads, refer to the User Inbox API documentation.

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 a simpler inbox mechanism, refer to the Inbox documentation for implementation details.

Parsing User Inbox Items

Once your backend retrieves the User Inbox data from the Actito REST API, your application can easily parse that response using the SDK’s helper method. This allows your app to transform the raw JSON payload returned by your backend proxy into strongly typed inbox items managed by the SDK along with other useful details such as the total number of inbox items and how many are unread.

Use the parseInboxResponse() method to convert the API response into an object composed of three properties:

• items — A list of ActitoUserInboxItem objects.
• count — The total number of inbox items.
• unread — The total number of unread messages.

Here's an example:

import { parseInboxResponse } from 'actito-web/user-inbox';

const json = /* The JSON response retrieved from your backend */
const { items, count, unread } = await parseInboxResponse(json);

// Update your UI with the parsed items contained in response

This approach ensures that your app can display and manage user-level inbox messages securely, without directly calling the Actito REST API or exposing sensitive credentials.

note

The response provided to parseInboxResponse() should match the JSON format returned by the User Inbox API endpoints, as retrieved by your backend. Make sure your backend acts as a proxy to the Actito REST API, handling authentication using your Master Secret and enforcing your own access controls.

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/user-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/user-inbox';

await markInboxItemAsRead(item);

Removing Messages

To remove a single message from the inbox:

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

await removeInboxItem(item);