콘텐츠로 건너뛰기

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 to

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

Wrong: the image is dropped
{
"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:

Right
{
"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 to
  • preset (string): code (format XXXXX-XXXXX) of a saved App Inbox preset. See How a preset is combined with the request.
  • content (object): per-locale content. localized_content maps 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 a preset supplies 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 returns 400. Without tab, 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.

Content of the inbox entry for one locale.

  • title (string): title of the entry. Required for the captioned and carousel layouts.
  • body (string): text of the entry. Required for every layout except banner.
  • icon_url (string): small image shown next to the entry.
  • banner_url (string): large image shown inside the entry. Required for the captioned and banner layouts.
  • layout_type (string): how the entry is displayed: classic, captioned, banner, or carousel. Empty means classic. Any other value returns 400.
  • carousel (array of CarouselSlide): slides of the carousel layout.
  • open_action (OpenAction): action performed when the user taps the entry.
  • open_actions (map<platform code, OpenAction>): per-platform override of open_action. See Per-platform tap actions.
  • custom_data (object): free-form JSON delivered to the SDK with the entry.
  • buttons (array of Button): 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 to
layout_typeRequired fields
classic or emptybody
captionedtitle, body, banner_url
bannerbanner_url
carouseltitle, body, 1 to 5 carousel slides
  • text (string): label of the button, up to 64 characters. Required.
  • text_color (string): label color as #RRGGBB or #RRGGBBAA. Empty uses the SDK default.
  • bg_color (string): background color as #RRGGBB or #RRGGBBAA. Empty shows the button as a link.
  • One action, required:
    • link (object): opens url. The same URL rules as for a slide url apply.
    • deep_link (object): opens a deep link by code, with optional params.
    • 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 to
  • image_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 example https://example.com/look-1 or a deep link such as myapp://looks/1. It needs a scheme and something after it, up to 2048 bytes. javascript:, data:, vbscript:, file:, and intent: links return 400. 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 to

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

PlatformCode
iOS1
Android3
Huawei17
Safari10
Chrome11
Firefox12
Web20

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 to

A 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.
  • carousel is taken from the preset only when the request has no slides for that locale. Slides taken from a preset have no url, so to add slide links, send the whole carousel in the request.
  • custom_data is taken from the preset only when the request has none for that locale. The two objects aren’t merged.
  • buttons are taken from the preset only when the request has no buttons for that locale.
  • tab isn’t taken from a preset. Set it in the request.

The combined content is then checked against the layout requirements.

An 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"
}
}
}