​
Why use a push permission prompt?

To send push notifications that can appear as banners, show on the lock screen, play sounds, and more, your app must first get the user’s permission. On iOS, Android, Huawei, Amazon, and Web this involves displaying a system-level permission prompt.

An iOS and Android device displaying the system-level permission prompt.

This guide is for mobile app push subscribers. For web push, see Web Permission Prompts.
On iOS, you can also use Provisional notifications, which quietly deliver to the notification center without prompting the user—ideal for testing or low-friction onboarding. For the recommended system-level permission prompt, keep in mind:
  • iOS only allows the permission prompt once.
  • Android allows it twice.
  • After that, users must manually enable notifications in system settings.
While you can trigger the prompt at any time using our requestPermission() SDK method, it’s critical to ask at the right moment and with proper context. Both Apple and Google strongly recommend explaining the value of your notifications first. The best way to do that? Use a “soft prompt”—a custom in-app message that introduces the ask. If the user accepts, the system prompt appears. If they decline, nothing happens—no harm done.

Example shows an in-app message that leads to a system-level push permission prompt.

​
Set up an in-app push permission prompt

1

Remove any automatic permission prompts

Before you begin, make sure your app isn’t already triggering the native push prompt automatically:
  • Remove requestPermission() or optIn() methods if you’re calling them on app start.
  • Remove native iOS calls to requestAuthorizationWithOptions and any methods generating push tokens.
  • Remove Android calls to requestPermissions and any methods generating push tokens.
Also, make sure you’re using the latest version of the OneSignal SDK in your app.
2

Create or edit the in-app message

Go to Messages > In-App, then either:
  • Edit the default Push Permission Prompt template, or
  • Click New Message to create your own.

Edit the default Push Permission Prompt template or create your own.

Set the audience to: Show to all users Don’t worry—this type of in-app message is automatically shown only to users who haven’t subscribed to push.

Set your audience as "Show to all users" because the "Push Permission Prompt" click action will make sure it is only shown to the unsubscribed subscriptions.

3

Customize the message design

Personalize the look, feel, and wording to fit your app. Keep it clear and helpful—let users know what kind of notifications they’ll get and why they’re valuable.See Design In-App Messages with Drag and Drop or Design in-app messages with HTML for details.

The in-app message block editor allows you to create messages asking users to opt in to push notifications.

4

Add the push permission prompt click action

Add a Push Permission Prompt click action to any button or image in your message. When tapped, the system prompt is shown.

The in-app message block editor allows you to add a click action to a button to prompt for push permission.

Example of the required permission prompt on iOS.

If a user has already denied permission, the button will direct them to your app’s notification settings instead.
In-app messages that have a “Push Permission Prompt” action will not be shown to users who have already allowed notifications.
5

Choose a trigger

The audience controls who is eligible to see the message. Triggers control when it’s shown.

Trigger options to control when the message is shown.

You can trigger the message:
  • On app open
  • After a set amount of session time
  • On a specific user event
  • Programmatically (more control)
For example, to wait until the user has spent at least 5 minutes in the app:

Triggers can be set to time when users see the in-app message.

6

Schedule and frequency

You can control how often the message appears:
  • Only once – Low chance of conversions
  • Every time conditions are met – Too aggressive
  • ✅ Multiple times – Recommended
Set a large max (e.g. 9999) and a delay between views (e.g. 2 weeks) to gently remind users over time. This means the message will show one time every 2 weeks for a total of 9999 times.We want the first number to be a very large amount because we always want to prompt unsubscribed users to subscribe but we don’t want to annoy them so we only ask every 2 weeks. You can change the cadence from 2 weeks to more or less depending on the use case.

Schedule when users will start seeing your in-app message and how often they see it.

Update your message and set it live. You can now monitor your stats and update the gap in between days as needed.

​
Programmatically show the required permission prompt

Developers: You can trigger the push permission prompt manually using requestPermission() or optIn() SDK methods. This is great for custom flows, such as:

​
Track push permissions and prompt results

When using in-app messages to prompt for push, you can track click actions with the In-app message click listener. For cases where the in-app message displays but the user doesn’t click the button, you can listen for the In-app message lifecycle events. For tracking the results of the system-level permission prompt, you can listen for events with the Push permission listener.
When using these SDK methods, you can send the events to your backend or analytics tool of choice.

​
FAQ

​
Can I still prompt users with provisional notifications?

Yes! In fact, if you use iOS provisional push notifications, it is recommended to still prompt users for push in this way but be strategic!

​
When did Android start requiring permission prompts?

Android started requiring explicit user permission for push notifications with Android 13 (API level 33), which was: