In-app message examples

In-app messages (IAM) are customizable, targeted messages that display within your mobile app. They enable you to:
  • Prompt user action like subscribing to push notifications or updating their location.
  • Promote new or underutilized features to targeted users.
  • Display announcements and news in real-time without releasing an app update.
  • Create surveys and carousels.
  • Help with onboarding and educational content.

​
Setup & requirements

You must have the OneSignal SDK installed in your app to use In-App Messages. Once complete, you can create and send in-app messages from the OneSignal dashboard without writing any code. Our SDK also has methods for advanced use cases like:
  • Triggering the message at specific times
  • Click-handling and deep linking
  • Pausing the message
  • Lifecycle management and more!

Mobile SDK Setup

Add OneSignal to your mobile app codebase.

In-app Message SDK methods

Developers: Access trigger, click handler, and lifecycle APIs.

In-app triggers

Control when messages appear based on user behavior or app activity.

In-app click actions

Define what happens when users interact with your message.

​
Send in-app messages

You can send in-app messages from the OneSignal dashboard and within Journeys.
Steps for sending messages with OneSignal:

Select the message channel

  • Go to Messages > In-App > New In-App
  • Use the options menu to edit, resume, or duplicate messages.

Options to duplicate or edit in-app templates

Choose a composition method

Set a name and label

  • Add internal tracking metadata.
  • API equivalent: name

Set an audience

Include or exclude Segments:
  • Send to default segment: Defaults to all “Subscribed Users” if none set.
  • Send to specific segments: Include and exclude segments explicitly. Multiple segments have an “OR” relationship; duplicate Subscriptions are automatically removed.
In-app messages are delivered to all mobile Subscriptions in the segment, regardless of push opt-in status. However, if your message contains a push prompt click action, it will not show to subscribed (opted-in) mobile Subscriptions.

Name, label, and audience segment selection interface

Targeting methodDashboardAPI
Segments✅✅
Filters (API only)❌✅
Aliases (API only)❌✅

​
Message design

Use our visual drag-and-drop editor or our HTML editor for more control.

Editing screen

Design with drag-and-drop

Use our visual editor to quickly build messages.

Design with HTML

Full control for developers to customize messages.

Pre-built HTML templates

Start from tested layouts and campaigns.

In-app JavaScript APIs for HTML

Add OneSignal’s click actions to your HTML messages.

Message Personalization

Add dynamic content to personalize messages for each user.

Multi-Language Messaging

Localize your content for global audiences.

​
Click actions

Customize what happens when users click elements in your message.

Click action options

Click Actions

Customize what happens when users click elements in your message.

Event Streams

Track interactions with the message.

SDK Click Handler

React to click events with our mobile SDK.

Deep Linking

Navigate users on click.

​
Triggers

Define when messages should appear during app sessions.

Trigger setup

Four trigger types:

On app open

Trigger when user launches the app.

Session duration

Delay X seconds after app open.

Since last message

Delay X time after last in-app message.

Custom triggers

Controlled via SDK addTrigger(s).

​
When should this message dismiss?

Messages can dismiss:
  • On user interaction (click, swipe)
  • After a set time (auto-dismiss)

Auto-dismiss after 90 seconds

​
Schedule & frequency

  • Start Showing: When message becomes eligible
  • Stop Showing: Set end date/time or “Show forever”

​
How often do you want to show this message?

  • Only once (default)
  • Every time triggers are met
  • Multiple times with custom repeat logic:
Examples:
  • Show 2 times with 1 hour gap
  • Show 12 times with 30 days gap

Example will show the message a total of 12 times every 30 days.

​
How in-app messages are shown

In-app messages are not actively pushed. Instead, they’re pulled at app start based on audience. Then displayed based on trigger logic.

In-app message display logic flow

The message will display if:
  1. The user meets audience criteria before a new session starts.
  • A new session starts when the user opens your app after it has been in the background or closed for at least 30 seconds.
  • If users have the app open when the message goes live or enters the segment(s) during the same session, they will need to put the app out of focus (close or background) for at least 30 seconds to be eligible to see the message.
  1. The trigger conditions are met.
  2. The scheduled time and frequency is valid.
If segment criteria change mid-session, users must reopen the app to see the message.

​
Testing

While testing, it is recommended to do the following:
1

Add versbose logging to your app

Add our setLogLevel method to Verbose in your app to get more detailed logs.
2

Make sure your Subscription is in the segment

As explained above in How in-app messages are shown, the user must match the audience criteria before a new session starts.
  • See Find Devices & Set Test Users if you don’t know your device’s Subscription ID.
  • Make sure your device’s Subscription is in the included segment(s) and not in the excluded segment(s) if being used.
  • Tip: You can add your device as a test Subscription and create or update the segment to include the Test Users filter.
3

Make sure the app is closed or out-of-focus for at least 30 seconds

This will ensure you are opening the app to create a new session and be eligible for the message.
4

Check trigger conditions

Make sure you satisfy the triggers for the message to be shown.
5

Check the schedule and frequency

6

Update the message and make sure it is active

  • Once the message is active, you can open the app on your device.
  • You should see the message display based on your trigger conditions.

​
Test & Preview button

Using the Test & Preview button will send a push notification to your test device selected. When you click the push to open the app, the in-app message will display. To use this feature, you must:
  • Make sure your device is a Test User.
  • Push notifications are only sent for testing purposes. Push will not be sent when the message is live.
  • You can open the app and send the “test message”. The in-app message will display.
  • Tag Substitution does not work for test In-App Messages.
  • If you are not seeing the message, make sure you have followed the testing steps.
  • To receive a test In-App Message, your device must be subscribed to push. Test IAMs are triggered by a push notification, so if your subscription has an invalid APNs token or you’re not subscribed to push, the test will not work.
Need help?Chat with our Support team or email support@onesignal.comPlease include:
  • Details of the issue you’re experiencing and steps to reproduce if available
  • Your OneSignal App ID
  • The External ID or Subscription ID if applicable
  • The URL to the message you tested in the OneSignal Dashboard if applicable
  • Any relevant logs or error messages
We’re happy to help!

​
Tutorials & use cases

Personalize in-app message

Step-by-step guide to personalize your in-app message with tags.

Target outdated app versions

Prompt users to update their app.

App store review prompts

Increase your ratings with timely review requests.

Create user surveys

Collect feedback inside your app.

Push permission prompts

Improve push opt-in rates.

Location permission prompts

Ask users to enable location tracking.

Create a tutorial

Setup a tutorial to help users understand new features of your app!