In-App Messaging

In-app messages are banner notifications that appear inside of your app. Aside from giving you the power to engage with users as they browse your app, they allow you to reach opted-out users, a segment of the app audience previously unreachable with this type of messaging.

With in-app messages, you can:

  • Create relevant, branded in-app messages that interface with existing Urban Airship features (e.g. Actions, Interactive Notifications, etc)

  • Reach opted-out and opted-in users unobtrusively

For more on in-app messaging use-cases, see: In-App Messaging Explained.


In-app messages work out-of-the-box on Android/Amazon and iOS with version 6.0 or later of the Urban Airship SDK. See the appropriate Platform page to get started.

Behavior and Appearance

In-app messages are banner notifications that can appear at either the top or bottom of your application. They behave largely like standard push notifications, in that they can include any element of Urban Airship’s rich feature set (interactive buttons, actions, etc), and they can be dismissed as you would dismiss a standard push notification. However, there are a few key differences regarding in-app message display behavior:

  • Duration: By default, an in-app message will only appear on a user’s screen for 15 seconds before disappearing. When sending in-app messages via the API, you can override this value with the duration key. There is currently no way to override the default value when sending in-app messages through the UI.

  • Sending multiple messages: An app will only hold onto a single in-app message at a time. If a valid message is waiting to be displayed in a user’s app, and a new message comes along, the new message takes the place of the prior one. Moreover, there is no way to specify an in-app message’s priority. A new message will always replace an old message.

By default, an in-app message will not display while a customer is browsing your app. If a customer is browsing your app while you send an in-app message, they will have to exit and later reopen the app before the message will display.

In-app messages will animate into the user’s screen. Depending on the API request specifications or dashboard configuration, the message will animate in from either the top or bottom of the user’s screen. Message dismissal on iOS is accomplished with a Drawer Pull, and dismissal on Android is accomplished by swiping the message, left or right, or clicking on the “X” icon. The image below shows both the top and bottom display styles for both Android and iOS devices:

Note that the message colors can be specified via the API or UI.

Getting Started

Assuming you have the proper requirements, getting started with in-app messages is quick and painless.

  • API: If you want to use the API to send your first in-app message, no setup is required! Proceed to our API documentation for details on creating your message.

  • UI: If you would like to use the UI to send your first in-app message, you have a small initial configuration step to complete, which is detailed below. After you have configured in-app messages, you’re ready to head to the Message Composer to send your first in-app message.

Configuring In-App Messages

Before you can send in-app messages, you must navigate to the Settings » Configuration page, and set the In-App Messages toggle to on:

Once you have enabled in-app messages, you need to configure display options. When you navigate to the In-App Messages tab, you will see the following options:

  • Primary Color: The color of the button text and message background. This is entered as a hex value.

  • Secondary Color: The color of the message font text, button background, and certain UI elements (e.g. drawer pull on iOS). This is entered as a hex value.

  • Position: Toggle whether the in-app message displays at the top or bottom of the screen.

  • Duration: The in-app message display duration. By default, this is set to 15 seconds. If you would like to set a different duration, select Specify and enter your desired value (in seconds).

Once you settle on an appropriate configuration, you’re ready to start sending in-app messages.


Q: Will opted-out users receive in-app messages?
A: Yes, in-app messages can be sent to your entire app audience, not just those opted-in to push notifications. There are a couple of caveats: certain platform restrictions exist (see What platforms are supported?, below), and iOS8 users who have disabled the Background App Refresh feature will not receive messages. It is also possible to allow your users to disable in-app messages, if you would like to present users with the choice.

Q: What versions of the SDK support in-app messages?
A: In-app messages require version 6.0+ of the Urban Airship SDK.

Q: What platforms are supported?
A: iOS8, Android API 14+ (Ice Cream Sandwich), and second generation or later Amazon devices are supported. iOS7 users can also receive in-app messages, though they must be opted in to push.