App Inbox payload reference
Reference for the AppInboxPayload message used by Notify when sending through the App Inbox channel.
app_inbox_payload sends a message through the App Inbox channel: it creates an entry in the user’s Message Inbox without sending a push notification. App Inbox is the channel, and Message Inbox is the in-app list where the entry appears. app_inbox_payload is set at the same level as payload and email_payload in segment or transactional, and only one payload field can be set in a request.
Unknown fields are dropped without an error
Anchor link toThe REST endpoint ignores every field it doesn’t recognize and returns no error for it. A misspelled field or a field placed at the wrong level is dropped, and the message is sent without it.
For example, a nested inbox object inside app_inbox isn’t part of this payload. The image in it is dropped, and the entry arrives without an image:
{ "app_inbox": { "title": "Weekend sale", "body": "Up to 50% off", "inbox": { "image_url": "https://cdn.example.com/sale.png" } }}Set the image in icon_url or banner_url directly inside app_inbox, and set the lifetime at the top level of app_inbox_payload:
{ "app_inbox_payload": { "content": { "localized_content": { "default": { "app_inbox": { "title": "Weekend sale", "body": "Up to 50% off", "icon_url": "https://cdn.example.com/sale.png" } } } }, "expiration_date": "2026-11-30T00:00:00Z" }}Check the field names on this page before you send, because the response doesn’t tell you that a field was skipped.
AppInboxPayload
Anchor link topreset(string): code (formatXXXXX-XXXXX) of a saved App Inbox preset. See How a preset is combined with the request.content(object): per-locale content.localized_contentmaps a locale code to an object with one key,app_inbox(AppInbox). Locale keys follow the same rules as in the push payload, including"default". Required, unless apresetsupplies the content.expiration_date(timestamp): when the entry is removed from the inbox. Must be in the future.expires_in(duration, e.g."604800s"): how long the entry stays in the inbox. Must be positive.tab(string): code of the inbox tab the entry is filed under. The tab must be a custom tab of the same application, not the All tab. Any other code returns400. Withouttab, the entry shows only in the All tab.
Set either expiration_date or expires_in, not both. If neither is set, the entry stays in the inbox for 30 days. expires_in is counted from the moment the API receives the request, also for a message scheduled for later.
If your account has a maximum inbox lifetime, a longer lifetime returns 400. The 30-day default is checked against this limit too.
AppInbox
Anchor link toContent of the inbox entry for one locale.
title(string): title of the entry. Required for thecaptionedandcarousellayouts.body(string): text of the entry. Required for every layout exceptbanner.icon_url(string): small image shown next to the entry.banner_url(string): large image shown inside the entry. Required for thecaptionedandbannerlayouts.layout_type(string): how the entry is displayed:classic,captioned,banner, orcarousel. Empty meansclassic. Any other value returns400.carousel(array ofCarouselSlide): slides of thecarousellayout.open_action(OpenAction): action performed when the user taps the entry.open_actions(map<platform code,OpenAction>): per-platform override ofopen_action. See Per-platform tap actions.custom_data(object): free-form JSON delivered to the SDK with the entry.buttons(array ofButton): up to 3 buttons shown under the entry text.
Every image URL, in icon_url, banner_url, and carousel, must be an absolute https URL. Any other value returns 400. The file format isn’t checked.
The layout and the slides reach the SDK inside the entry’s custom data, under the keys displayType and carousel. Don’t use these two keys in your own custom_data, because they are overwritten. The buttons reach the SDK the same way, under the key buttons. If the entry has buttons, a buttons key in your custom_data returns 400.
Required fields by layout
Anchor link tolayout_type | Required fields |
|---|---|
classic or empty | body |
captioned | title, body, banner_url |
banner | banner_url |
carousel | title, body, 1 to 5 carousel slides |
Button
Anchor link totext(string): label of the button, up to 64 characters. Required.text_color(string): label color as#RRGGBBor#RRGGBBAA. Empty uses the SDK default.bg_color(string): background color as#RRGGBBor#RRGGBBAA. Empty shows the button as a link.- One action, required:
link(object): opensurl. The same URL rules as for a slideurlapply.deep_link(object): opens a deep link bycode, with optionalparams.copy_text(string): copies the text to the clipboard.custom_data(object): passes the data to the app in the button click callback. Must not be empty.
{ "app_inbox": { "body": "Your order has shipped", "buttons": [ { "text": "Track order", "bg_color": "#1A73E8", "text_color": "#FFFFFF", "link": { "url": "https://example.com/orders" } }, { "text": "Copy code", "copy_text": "SALE20" } ] }}CarouselSlide
Anchor link toimage_url(string): image of the slide. Required.caption(string): text shown with the slide.url(string): link opened when the user taps the slide, for examplehttps://example.com/look-1or a deep link such asmyapp://looks/1. It needs a scheme and something after it, up to 2048 bytes.javascript:,data:,vbscript:,file:, andintent:links return400. Empty means the tap runs the entry’s action. One value serves every platform.
A slide link opens instead of the entry’s action. If the slide has no link, or the device can’t open it, the entry’s action runs. The Web SDK inbox widget handles slide links this way. On iOS and Android, iOS SDK 7.3.1 and later and the Android SDK versions released after 6.17.2 do. In iOS SDK 7.2.8–7.3.0 and Android SDK 6.15.1–6.17.2, a slide link opens only when the entry has no action.
{ "app_inbox": { "layout_type": "carousel", "title": "New arrivals", "body": "Swipe to see the collection", "carousel": [ { "image_url": "https://cdn.example.com/look-1.png", "caption": "Look 1", "url": "https://example.com/looks/1" }, { "image_url": "https://cdn.example.com/look-2.png", "caption": "Look 2" } ] }}Per-platform tap actions
Anchor link toopen_actions sets a different tap action for a platform. The key is the numeric platform code, written as a string in JSON. Only App Inbox platforms are accepted, any other key returns 400:
| Platform | Code |
|---|---|
| iOS | 1 |
| Android | 3 |
| Huawei | 17 |
| Safari | 10 |
| Chrome | 11 |
| Firefox | 12 |
| Web | 20 |
On web platforms, an action can also open a web popup: { "web_popup": { "code": "XXXXX-XXXXX" } }. web_popup is accepted only for the web platform codes, and all web platforms in one entry must use the same popup code.
{ "app_inbox": { "body": "Your order has shipped", "open_action": { "link": { "url": "https://example.com/orders" } }, "open_actions": { "1": { "deep_link": { "code": "XXXXX-XXXXX", "params": { "screen": "orders" } } }, "11": { "web_popup": { "code": "XXXXX-XXXXX" } } } }}How a preset is combined with the request
Anchor link toA preset fills the fields that the request leaves empty, separately for each locale. A field set in the request always wins over the preset.
- The preset must belong to the application in the request. Otherwise the request returns
400. - A locale that exists only in the preset is added to the message.
carouselis taken from the preset only when the request has no slides for that locale. Slides taken from a preset have nourl, so to add slide links, send the wholecarouselin the request.custom_datais taken from the preset only when the request has none for that locale. The two objects aren’t merged.buttonsare taken from the preset only when the request has no buttons for that locale.tabisn’t taken from a preset. Set it in the request.
The combined content is then checked against the layout requirements.
Errors
Anchor link toAn invalid payload returns 400 (INVALID_ARGUMENT) with a field violation that names the field, for example app_inbox_payload.content.localized_content[default].app_inbox.banner_url.
Send an App Inbox entry to users
Anchor link to{ "transactional": { "application": "XXXXX-XXXXX", "platforms": ["IOS", "ANDROID"], "users": { "list": ["user-42"] }, "schedule": { "immediately": true }, "app_inbox_payload": { "content": { "localized_content": { "default": { "app_inbox": { "layout_type": "captioned", "title": "Weekend sale", "body": "Up to 50% off until Sunday", "banner_url": "https://cdn.example.com/sale-banner.png", "open_action": { "link": { "url": "https://example.com/sale" } } } } } }, "expires_in": "259200s" } }}