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.

This module provides all the APIs required to parse, open, and manage user-specific inbox messages. To enable this functionality, include the actito_user_inbox module in your project's pubspec.yaml.

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

Use the parseResponse() 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

import 'package:http/http.dart' as http;

final httpResponse = await http.get(
  Uri.parse('https://{{YOUR_API}}/user-inbox'),
  headers: {
    'Authorization': 'Bearer ...',
  },
);

final response = await ActitoUserInbox.parseResponseFromString(httpResponse.body);

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

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 User Inbox items

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

final ActitoUserInboxItem item;

final notification = await ActitoUserInbox.open(item);

// Optional: Present the notification with Push UI.
await ActitoPushUI.presentNotification(notification);

Managing User 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:

final ActitoUserInboxItem item;

await ActitoUserInbox.markAsRead(item);

Removing messages

To remove a single message from the inbox:

final ActitoUserInboxItem item;

await ActitoUserInbox.remove(item);