How the App Inbox works
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.
A channel of a push notification
Section titled “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 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
Section titled “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
Section titled “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
Section titled “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 withenablePushEngagementTracking()). - 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
inboxMessageIdand can open that message (InboxService.getMessageByIdin React Native; theRelevaNavigateToInboxnotification 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
Section titled “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
inboxMessageReadevent; 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
inboxMessageClickevent. 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 aninboxMessageDeleteevent. 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
Section titled “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:
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 callawait 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-countawait InboxService.loadMore(); // next pageawait 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:
let client = RelevaClient(realm: "<realm>", accessToken: "<access token>")client.setProfileId("DEMO-CUSTOMER-1001")client.initializeInbox()
// Observe InboxService.shared: state.messages, unreadCount, isLoading, hasMoreclient.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 tapsSetting 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
Section titled “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.