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.

📘

Using web push?

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.

---

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.

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.

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.

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.

If a user has already denied permission, the button will direct them to your app's notification settings instead.

📘

Displayed to unsubscribed subscriptions only

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.

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:

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.

👍

Push prompt with in-app message setup complete!

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:

• A Preference center
• A user profile screen
• Specific in-app events

---

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:

• Released: August 2022 (Pixel devices)
• Required for target SDK: As of August 31, 2023, all new apps and updates on Google Play must target API level 33 or higher.
• Source: Google's developer guide on notification permissions

---