Skip to main content
In-app messages (IAM) are customizable, targeted messages that display within your mobile app. They enable you to:
  • Prompt User actions 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
Examples of in-app messages including promotions, surveys, and feature announcements

In-app message examples

​
In-app setup

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

Mobile SDK setup

Add OneSignal to your mobile app codebase.

In-app message SDK methods

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.

How to create and send in-app messages in OneSignal

Dashboard

Compose and send in-app messages from the OneSignal dashboard.

Journeys

Build automated, multi-step, and multi-channel flows.

​
Send from the dashboard

Select the message channel

Select Create… then choose your message channel. You can also navigate to Messages or Templates to view previous messages.
OneSignal dashboard showing create message options

Create a new message in the OneSignal dashboard.

Choose a composition method

Set a name and label

Add internal metadata for tracking and reporting. API equivalent: name

Select your audience

Choose which users receive the message. You can include and exclude segments to target specific groups. Defaults to all “Subscribed Users” if no segment is set.
Dashboard fields for message name, label, and audience segment selection

Name, label, and audience segment selection in the dashboard.

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.

​
Message design

Use the visual drag-and-drop editor or the HTML editor for more control.
OneSignal in-app message block editor showing drag-and-drop design interface

In-app message block editor interface

Design your in-app message

Full reference for the in-app message editor, blocks, and Carousel.

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 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.
OneSignal in-app message editor showing click action dropdown options

Click action options in the in-app message editor

Click actions

Configure what happens when Users click elements in your message.

Event Streams

Track interactions with the message.

SDK click handler

React to click events with the mobile SDK.

Deep linking

Navigate Users to specific screens on click.

​
Triggers

Define when messages should appear during app sessions.
OneSignal dashboard showing in-app message trigger configuration options

Trigger setup options for in-app messages

Four trigger types are available:
  • On app open: Display when the User launches the app.
  • Session duration: Delay a set number of seconds after app open.
  • Since last message: Delay a set time after the last in-app message was shown.
  • Custom triggers: Controlled via the SDK addTrigger(s) method for precise timing based on User behavior.

​
Dismiss behavior

Messages can dismiss:
  • On User interaction (click, swipe)
  • After a set time (auto-dismiss)
OneSignal dashboard showing in-app message auto-dismiss timer set to 90 seconds

Auto-dismiss configuration set to 90 seconds

​
Schedule and frequency

  • Start showing: When the message becomes eligible to display
  • Stop showing: Set an end date/time or “Show forever”

​
Display frequency

  • Only once (default)
  • Every time trigger conditions are met
  • Multiple times with custom repeat logic
Examples:
  • Show 2 times with a 1 hour gap
  • Show 12 times with a 30 day gap
OneSignal dashboard showing in-app message frequency set to 12 times every 30 days

Frequency configuration: show the message 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.
Flowchart showing the lifecycle of an in-app message from audience check to display

In-app message display logic flow

The message displays 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 the User has the app open when the message goes live or enters the Segment during the same session, they must close or background the app for at least 30 seconds to be eligible.
  2. The trigger conditions are met.
  3. The scheduled time and frequency are valid.
If Segment criteria change mid-session, the User must reopen the app to see the message.

​
Testing

1

Add verbose logging to your app

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

Make sure your Subscription is in the Segment

As explained in How in-app messages are shown, the User must match the audience criteria before a new session starts.
  • See Find devices and 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).
Add your device as a test user and create or update the Segment to include the Test Users filter.
3

Close or background the app for at least 30 seconds

This ensures you open the app to create a new session and become 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

  • Make sure the “Start showing” and “Stop showing” dates are set correctly.
  • Set display frequency to “Every time trigger conditions are satisfied” while testing.
6

Update the message and make sure it is active

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

​
Test and preview

The Test & Preview button sends a push notification to your selected test device. When you click the push to open the app, the in-app message displays. Requirements and notes:
  • Your device must be a test User
  • Your device must be subscribed to push — test in-app messages are triggered via push notification (this is not required for normal in-app messages)
  • Push is only sent for testing purposes and will not be sent when the message is live
  • If you are not seeing the message, follow the testing steps above
    Tag substitution does not work for test in-app messages.
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 and use cases

Personalize in-app messages

Personalize your in-app message content 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 with pre-permission prompts.

Location permission prompts

Ask Users to enable location tracking.

Set up a tutorial

Guide Users through new features of your app.

​
Analytics

Track message performance and engagement.

In-app message reports

Impressions, clicks, dismissals, and conversion metrics for in-app messages.

Analytics overview

All analytics options available in OneSignal.

Event Streams

Stream push events to your data warehouse or BI tools in real time.

​
FAQ

​
Do in-app messages require push notification permission?

No. In-app messages are delivered to all mobile Subscriptions in the target Segment, regardless of push opt-in status. They display inside the app during an active session.

​
Why isn’t my in-app message showing?

The most common cause is that the User’s session didn’t refresh. The User must close or background the app for at least 30 seconds, then reopen it to start a new session. Also verify the User is in the target Segment and that trigger conditions are met. See Testing for a full checklist.

​
Can I send in-app messages via the API?

You must create in-app messages within the OneSignal dashboard. You can include the in-app message within Journeys and enter the user into the Journey via Custom Events triggered from the API.

​
How are in-app messages different from push notifications?

In-app messages display inside your app while the User is actively using it. Push notifications appear on the device’s notification tray and can reach Users even when the app is closed. In-app messages do not require push permission and are pulled at session start rather than pushed from the server.

​
Can I use in-app messages on web?

No. In-app messages are only available for mobile apps with the OneSignal mobile SDK installed. For web, consider using web push notifications instead.