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.

Requirements

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

• You have successfully completed the Getting Started guide and included the ActitoInboxKit dependency

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

private var cancellables = Set<AnyCancellable>()

Actito.shared.inbox().itemsStream
    .sink { items in
        // handle inbox items
    }
    .store(in: &cancellables)

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

private var cancellables = Set<AnyCancellable>()

Actito.shared.inbox().badgeStream
    .sink { badge in
        // handle unread badge count
    }
    .store(in: &cancellables)

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

// Retrieve the list of inbox items
Actito.shared.inbox().items

// Retrieve the current unread badge count
Actito.shared.inbox().badge

Opening Inbox items

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

let controller: UIViewController
let item: ActitoInboxItem

do {
    let notification = try await Actito.shared.inbox().open(item)
    Actito.shared.pushUI().presentNotification(notification, in: controller)
} catch {
    // Handle 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:

let item: ActitoInboxItem

do {
    try await Actito.shared.inbox().markAsRead(item)
} catch {
    // Handle error
}

To mark all messages as read:

do {
    try await Actito.shared.inbox().markAllAsRead()
} catch {
    // Handle error
}

Removing messages

To remove a single message from the inbox:

let item: ActitoInboxItem

do {
    try await Actito.shared.inbox().remove(item)
} catch {
    // Handle error
}

To clear all messages from the inbox:

do {
    try await Actito.shared.inbox().clear()
} catch {
    // Handle error
}