# App Inbox payload reference

Reference for the `AppInboxPayload` message used by [`Notify`](/developer/api-reference/messaging-api-v2/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](/developer/guides/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.

<Aside type="note">
To add a push notification to the inbox as well, send a regular [`payload`](/developer/api-reference/messaging-api-v2/payload-reference/) with the [`inbox`](/developer/api-reference/messaging-api-v2/payload-reference/#inbox) field instead.
</Aside>

## Unknown fields are dropped without an error

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:

```json title="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`:

```json title="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

- `preset` (string): code (format `XXXXX-XXXXX`) of a saved [App Inbox preset](/product/content/app-inbox-presets/). See [How a preset is combined with the request](#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`](#appinbox)). Locale keys follow the same rules as in the [push payload](/developer/api-reference/messaging-api-v2/payload-reference/#localizedcontent), 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.

## AppInbox

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`](#carouselslide)): slides of the `carousel` layout.
- `open_action` ([`OpenAction`](/developer/api-reference/messaging-api-v2/payload-reference/#openaction)): action performed when the user taps the entry.
- `open_actions` (map&lt;platform code, `OpenAction`&gt;): per-platform override of `open_action`. See [Per-platform tap actions](#per-platform-tap-actions).
- `custom_data` (object): free-form JSON delivered to the SDK with the entry.
- `buttons` (array of [`Button`](#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

| `layout_type` | Required fields |
|---|---|
| `classic` or empty | `body` |
| `captioned` | `title`, `body`, `banner_url` |
| `banner` | `banner_url` |
| `carousel` | `title`, `body`, 1 to 5 `carousel` slides |

### Button

- `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.

```json
{
  "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

- `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.

```json
{
  "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

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

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

```json
{
  "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

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](#required-fields-by-layout).

## Errors

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

```json
{
  "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"
    }
  }
}
```

## Related

<CardGrid>
  <LinkCard title="Notify" href="/developer/api-reference/messaging-api-v2/notify/" />
  <LinkCard title="Payload reference" href="/developer/api-reference/messaging-api-v2/payload-reference/" />
  <LinkCard title="App Inbox presets" href="/product/content/app-inbox-presets/" />
</CardGrid>