OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Sending In-App Messages

OneSignal features - Sending In-App Messages with the OneSignal Messaging composer

In Messages > In-App see the out-of-the-box In-App templates provided by OneSignal and your recent sent or scheduled messages.

To create a new message, use the pre-created OneSignal Templates or click on New In-App.


OneSignal has five out-of-the-box In-App templates for you to quickly get started. These templates are professionally designed with rich-media content to help you deliver a quality experience to your app users. These include: Welcome Message, Push Permission Prompt, Promotions, New Feature Announcements, and App Store Rating request.

You can customize these templates with your own branding and set them to an active state in a few minutes.

Create a New In-App

OneSignal In-App Messaging works similar to our existing New Push Message creation flow, where you select your audience, add a trigger, craft your message, and schedule it for delivery.

Add a Message Name for your records to help easily find this later as you create more!

Step 1 - Audience

Select the audience eligible to receive your message. By default, messages will go to All users, but you can change the default segment.

You may also include and exclude segments of users if you've set up User Segments.


Includes Unsubscribed Devices

Segments for In-App Messages include both Subscribed & Unsubscribed mobile devices.

Example: Rate My App

Let's say you want to ask all users with over 3 sessions to rate your app. You can setup a segment using Session Count > 3. Optional: You can setup a second segment to exclude users that already rated the app. You can track users that were asked to rate already using Data Tags within the the In-App Message Click Handler method on each SDK.

Step 2 - Design Your In-App Message

This is where you create the message shown to your users.

Message Type

This is where the In-App Message will be located and how it appears on the screen.

Message TypeDescription
TopDrops down from the top of the screen.
CenterExpands out from the center to partially fill screen.
BottomPops up from the bottom of the screen.
FullExpands out from the center to mostly fill screen.

In-App Messages work in Portrait and Landscape mode.


Click Add Block to create a Button, Image, or Text elements.

You can drag, clone, delete, show/hide advanced settings of blocks using the options at the top right of each block.

Text Block

Text blocks provide Color, Size and Alignment options.
Not Currently Available: font, italicized, and bold options.
If you want to setup different languages, you will need to setup different IAM with text blocks in the languages you desire. Use Segments to setup Audience by Language.

Image Block

Click the Upload button or add a direct url to the image (make sure it includes the file extension like .png, .gif, .jpg).

If an image is clicked, it will not remove the IAM by default, you must select an option using the Add Click Action button.

Button Block

Button blocks provide Button Text, Background Color, Text Color, Size and Alignment options.
Not Currently Available: font, italicized, and bold options.
If you want to setup different languages, you will need to setup different IAM with blocks in the languages you desire. Use Segments to setup Audience by Language.

Clicked buttons will remove the IAM by default. If you don't want the button to dismiss the IAM, you must select the options button in the top right > Show Advanced Settings > Uncheck Dismiss on Click

Buttons can do more than dismissing the IAM if you select an option in Add Click Action.

Add Click Action

Click Actions can be added to Button and Image Blocks.

Click ActionDescription
URLOpens an in-app browser to the URL you specify.
Push Permission Prompt (iOS)Prompts iOS devices to subscribe to push if they click the button.
Location Permission PromptPrompts iOS and Android devices to opt-in for Location-Triggered Notifications.
Custom Action IDUsed for detecting the block clicked within the SDK In-App Message Click Handler method.

See How to Deep Link From An IAM for more details.

Example: Rate My App Actions

If the user clicks the image or button, I can send them to the app store to rate my app. Using URL Click Action and add the iOS or Android Deep Link to Market. This will require 2 In-App Messages and 2 Segments (one for android and another for iOS). You can easily duplicate In-App Messages so you don't need to recreate the content, just add the correct segment to target and update the URL.

If the user clicks the button to dismiss, you can add a "Custom Action ID" like tagUserDismissReview. This will be detected in the In-App Message Click Handler where you can Add a Data Tag that the user clicked "No" to rate my app.

class ExampleInAppMessageClickHandler implements OneSignal.InAppMessageClickHandler {
    // Example of an action id you could setup on the dashboard when creating the In App Message
    private static final String ACTION_ID_MY_CUSTOM_ID = "tagUserDismissReview";

    public void inAppMessageClicked(OSInAppMessageAction result) {
       if (ACTION_ID_MY_CUSTOM_ID.equals(result.clickName)) {
          Log.i("OneSignalExample", "Custom Action took place! Starting YourActivity!");
          OneSignal.sendTag("rated_app", "no");
let handler: OSHandleInAppMessageActionClickBlock = { action in
    var message: String? = nil
    if let clickName = action?.clickName, let clickUrl = action?.clickUrl, let firstClick = action?.firstClick, let closesMessage = action?.closesMessage {
        message = String(format: "Click Action Occurred: clickName:%@ clickUrl:%@ firstClick:%i closesMessage:%i", clickName, clickUrl as CVarArg, firstClick, closesMessage)
        print(message ?? "no message")
      if clickName == "tagUserDismissReview"{
        OneSignal.sendTag("rated_app", "no");


Test Sending the Message

You can test In-App Messages on your Test Devices by clicking "Send to Test Device" button.

This will send a push notification that you click to open the app and view the In-App Message test.

You will not see a push notification when setting the In-App Messages live.

Your device must be subscribed to get the Test In-App Message. The test will not work if your device is unsubscribed, but non-test In-App Messages will work on unsubscribed devices.

Step 3 - Triggers

The trigger is a custom option for when to show this message. You can trigger the IAM when the user opens the app or setup a custom triggers programmatically with addTrigger method.
Triggers can be combined with AND and OR operators to only show under very specific conditions.

On app openShow message upon next app open.

Use this to make sure all users within the segment get the message when they open the app.
In-App TriggerShow message when user performs certain action.

Tigger you set with code using the In-App addTrigger methods.
Session DurationShow message after x seconds within the current app session.
Duration Since Last In-AppShow message after x seconds since the most recent in-app message.


Advanced Triggering

More details on how triggers work below in the FAQ.

Step 4 - Schedule

You can schedule when and for how long the in-app message should be available to send. You can set Advanced options to dismiss the IAM automatically after x amount of time.

Start Showing is when the message will begin to be presented to users. If the specific time set has not been reached, the message cannot be triggered.

Stop Showing is the time after which the message cannot be triggered any longer.

Schedule Advanced

By default In-App Messages will only show 1 time to a device and must be dismissed by a user action (clicking the x button in the corner or one of the elements or swiping the message away). Using Advanced Schedule options you can control these aspects.


Minimum OneSignal SDK Version Required

Make sure to update your OneSignal SDK to the latest version for this to work.

For repeat messages, your app must show a minimum OneSignal SDK Version of 3.13.0 on Android and 2.13.0 on iOS. You can view your device's OneSignal SDK Version in Audience > All Users > SDK Version Column.

When should this message dismiss?

Select Dismiss after certain amount of time to set how long the message should wait before dismissing itself.

How often do you want to show this message?

Select Every time trigger conditions are satisfied to show this message each time the Trigger events are met.

Option Multiple times allows you to set a specific amount of times this message can be shown within a set timeframe.

For example, if you set: "2 times with a gap of 1 hours in between" - The message will be allowed to trigger a total of 2 times. The first time when the triggers are met, then the 2nd time when the triggers are met and 1 hour has passed.

If you set "12 times with a gap of 30 days in between" - The message will show roughly once a month for a year.


Triggers Must Be Satisfied

If the Trigger is On app open or Session Duration then the user must open the app to see it again.

If trigger is Duration since last in-app then the message will show after this is satisfied if longer than the repeat timeframe.

If the trigger is a programmatic In-app trigger, then the method must be called again after the timeframe.


How do triggers work?

In-App Message triggers are handled by our SDK using the addTrigger or addTriggers method. A trigger is a key: value pair of string or integer data that you set programmatically in your app when an event occurs.

For example, if you want to send an IAM when a user reaches level 5 and level 10 of your game. Each time the use grows a level, you would call for example OneSignal.addTrigger("level", 1); then when they reach level 2, you simply update the trigger OneSignal.addTrigger("level", 2); and so on. At OneSignal.addTrigger("level", 5); you can then have the IAM show to the user by setting the key as level is 5 or level is greater than or equal to 5

Then continue to update the level up to level 10 or higher if you want to continue this flow.


Triggers are not tags.

The value of the trigger is not viewable within the OneSignal dashboard, but you can view the current trigger value programmatically with the getTriggerValueForKey method on the OneSignal SDK.

How can I target my unsubscribed users?

Unlike push notifications, in-app messages will be sent to subscribed and unsubscribed users. If you want to target only unsubscribed users:

  1. Select the segment of devices you want to target.
  2. Set the in-app message to only send with a trigger.
  3. Within the app set the in-app trigger to fire only if the user is unsubscribed. You can use the getPermissionSubscriptionState method to check the subscription status of the device.

Can the in-app message look like the basic device system dialogue?

While in-app messages do not utilize the device’s basic system dialogue, it can be customized to be shown in the center middle of the device like the system dialogue and show just a plan background and text.

Will OneSignal support localization on the in-app messages?

Not for v1 in the same way as supported currently with push, but we plan to add this. Currently you can setup different in-app messages for different languages and target a Segment based on the language our SDK automatically detects.

Is the WYSIWYG preview accurate?

The WYSIWYG preview is very close to what your users will actually see. However devices have a range of screen dimensions and so we have an easy to use preview on device option that will send the in-app message to any test device you'd like immediately to take a look at it on your own phone.

Can I upload my own HTML template?

Currently no. If this is a a feature you would like, please contact support with your use case and details of how you would like to use.

Is tag substitution available?

Currently no. If this is a a feature you would like, please contact support with your use case and details of how you would like to use.

Can I send in-app messages via the API?

Currently no. If this is a a feature you would like, please contact support with your use case and details of how you would like to use.

What are the dimension limits for background image?

We show IAMs based on the dimensions of the phone currently being displayed on. There are a few common aspect ratios for devices and resolutions (especially for Android) which could all affect the viewing of the IAM.

A 16:9 aspect ratio is the most common for devices, but 4:3 and 3:2 aspect ratios are close compromises.

How to deep link within the app from an IAM?

If you just want to open a URL when clicking the IAM, add the URL to the button or image "URL" field. An in-app browser will appear with the url.

If you want to deep link into another page of the app, using the Click Action you can specify an "Action Name". This action name is available within the In-App Message Click Handler method inside the OSInAppMessageAction object called clickName.

When you detect this clickName you can then deep link to the page in your app.

Example: If you normally detect on a push notification the data "deepLink": "page3" using the Notification Opened Handler, then in the In-App Message Click Handler method you would specify page3 for the clickName.

You can have different clickName's for the image, button and background. If you don't sent a clickName, then it will be "null" and you can ignore it.

Updated about a month ago

Sending In-App Messages

OneSignal features - Sending In-App Messages with the OneSignal Messaging composer

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.