# How the App Inbox works

> What an App Inbox message is, how it differs from a push notification, who receives it, how it is personalised, when it expires, what read and delete mean, how the app keeps its inbox in sync, and where the results show up.

App Inbox is a persistent message centre inside your Android or iOS app. A push notification is gone once it is dismissed; an inbox message stays until the shopper deletes it or it expires. Use it for offers, order news and announcements the shopper should be able to find again.

This page explains how a message gets from the admin into a shopper’s inbox and what the app sees. For the endpoint-by-endpoint reference, read the [Inbox API overview](https://releva.ai/documentation/reference/inbox/overview/).

## A channel of a push notification

There is no separate “inbox message” object in the admin. You create an inbox message by ticking **App Inbox** as a channel of a push notification under **Marketing Channels › Push Notifications**, and writing the message on the **App Inbox** tab with its editor. The same notification can also send a visible push on **Android** and **IOS**, or be inbox-only. [How push notifications work](https://releva.ai/documentation/learn/push-notifications/how-push-notifications-work/) covers the form; the inbox-specific parts are:

| Setting                                          | What it does                                                                                                                                                                       |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **App Inbox** channel checkbox                   | Adds the inbox message. It needs Firebase credentials on the shop (“Android, iOS, and App Inbox require Firebase credentials.”), because the inbox is synced through a silent push |
| **App Inbox** tab                                | Title and body of the message. The body is built in the Releva builder and stored as design JSON (in the Unlayer format), which the SDKs render natively                           |
| **Expiry (days)**                                | 1 to 365 days to keep the message in the inbox. “Leave empty for no expiry.”                                                                                                       |
| **Test** on the App Inbox tab                    | Delivers the message to one profile (by email, phone or profile id) without sending a push. Available after the notification is saved                                              |
| **If max push notifications per day is reached** | **Reschedule** cannot be combined with App Inbox; the form switches it off when you tick the channel                                                                               |

Internally Releva stores one message template per push notification, named `[Inbox] <push notification name>`. Removing the **App Inbox** channel deletes the template and every shopper’s copy of it.

## Who receives it

A campaign or workflow sends the push notification; the inbox message goes to every profile in the audience that has a registered **app push token** (`POST /api/v0/appPush/tokens`, which the mobile SDKs call for you). A profile without an app token gets no inbox message, even for an inbox-only notification, because there is no device to sync. A/B test control groups are excluded like for any other channel.

Shoppers who are over the daily push limit still get the inbox message. They receive a silent sync push instead of the visible one, so the message appears in the app without a notification.

## Personalised when sent, then frozen

Each shopper gets their own copy of the message. The title and the body are rendered with the profile’s data (Handlebars merge tags) at send time, together with the delivery time and the expiry date. Editing the template afterwards changes future sends only; copies that are already in inboxes keep their text. There is no way to recall a delivered message.

Every delivery writes an `inboxMessageSend` event on the profile with the message template id and the campaign, segment and push notification ids.

## Delivery, then sync

Releva creates the inbox copies **before** it sends the push, so the app can refresh the moment the push arrives. The push payload carries `inbox_sync: "true"` (and, when the push’s mobile **Target** is **Open Inbox**, `target: "inbox"` with the template’s `inboxMessageId` in `navigate_to_parameters`). Shoppers over the daily limit get a data-only push with the same `inbox_sync` flag.

The SDKs act on it:

* On a sync signal in the foreground, the inbox refreshes (React Native: forward the FCM data message to `EngagementTrackingService.handleForegroundMessage`; Swift: automatic with `enablePushEngagementTracking()`).
* When the app comes back to the foreground and the cached inbox is older than 5 minutes, it refreshes.
* On a tap with target **Open Inbox**, the app receives `inboxMessageId` and can open that message (`InboxService.getMessageById` in React Native; the `RelevaNavigateToInbox` notification in Swift).

Without the SDK, call `GET /inbox/messages` and `GET /inbox/unread-count` yourself when your app receives the `inbox_sync` push or comes to the foreground.

## Read, delete, expire

* **Read** is a flag on the shopper’s copy. The app sets it with the read endpoint when the shopper opens a message, or marks everything read at once. Reading writes an `inboxMessageRead` event; reading an already-read message writes nothing.
* **Tapping a link or button** in the message is reported separately with the action endpoint and writes an `inboxMessageClick` event. It does not mark the message read, so the SDK widgets do both.
* **Delete** hides the copy for good (status `deleted`); it cannot be restored and writes an `inboxMessageDelete` event. The list and the unread count skip it.
* **Expired** copies (past **Expiry (days)**) are hidden from the list and the count, but kept. Messages without an expiry stay until deleted.

Everything is scoped to the shop and the `userId`: a message id from another shopper or shop answers `404`.

## Using the SDKs

Both mobile SDKs wrap the six endpoints, cache the inbox on the device, update the state optimistically and roll back when a call fails, and render the message body for you.

React Native (`@releva-ai/sdk-react-native`), after `setProfileId`:

```plaintext
import { RelevaClient, InboxService, InboxMessageWidget } from '@releva-ai/sdk-react-native';


const client = new RelevaClient('<realm>', '<access token>');
await client.setProfileId('DEMO-CUSTOMER-1001'); // becomes userId on every inbox call
await client.initializeInbox();                   // restores the cache, refreshes if stale


InboxService.addListener((state) => {
  // state.messages, state.unreadCount, state.isLoading, state.hasMore
});


await InboxService.refresh();                 // GET messages + GET unread-count
await InboxService.loadMore();                // next page
await InboxService.markAsRead(message.id);
await InboxService.markAllAsRead();
await InboxService.deleteMessage(message.id);


<InboxMessageWidget message={message} onLinkTap={(url) => Linking.openURL(url)} />
```

`InboxMessageWidget` reports the action for you when a link is tapped. The inbox is on in the `full` and `messagingOnly` config presets and off in `trackingOnly` and `pushOnly`; `initializeInbox()` does nothing when it is off. Pages are 20 messages.

Swift (`RelevaSDK`), after `setProfileId`:

```plaintext
let client = RelevaClient(realm: "<realm>", accessToken: "<access token>")
client.setProfileId("DEMO-CUSTOMER-1001")
client.initializeInbox()


// Observe InboxService.shared: state.messages, unreadCount, isLoading, hasMore
client.inbox.refresh()
client.inbox.loadMore()
client.inbox.markAsRead(message.id)
client.inbox.markAllAsRead()
client.inbox.deleteMessage(message.id)


InboxMessageView(message: message) { url in /* open url */ }   // reports the action on link taps
```

Setting a different profile id clears the cached inbox and fetches the new shopper’s messages. iOS apps that use the Expo adapter need APNs import enabled on the account for silent inbox sync; ask your account manager.

The web SDK (`releva-sdk-js`) has no inbox support.

## Where the results show up

The push notification’s statistics card shows **Inbox Sent**, **Inbox Reads** and **Inbox Clicks** next to the push numbers, defined on the `inboxMessageSend`, `inboxMessageRead` and `inboxMessageClick` events. The statistics attribute events by `pushNotificationId`, which only the delivery event carries, so in the current code **Inbox Sent** is filled while **Inbox Reads** and **Inbox Clicks** stay at 0. The read, click and delete events are still on the profile’s timeline. See [How push notifications work](https://releva.ai/documentation/learn/push-notifications/how-push-notifications-work/#sending-and-statistics).

## Next steps

* [Inbox API overview](https://releva.ai/documentation/reference/inbox/overview/): Read, mark and delete inbox messages with a working request for each endpoint.
* [How push notifications work](https://releva.ai/documentation/learn/push-notifications/how-push-notifications-work/): Learn how push notifications reach your app.
* [Send a push notification with a workflow](https://releva.ai/documentation/guides/push-notifications/send-a-push-notification-with-a-workflow/): Test a notification and hand it to a workflow.
* [Push notifications API overview](https://releva.ai/documentation/reference/push-notifications/overview/): Register your app’s push token with Releva.