Skip to main content

​
Why use a push permission prompt?

To send push notifications that appear as banners, show on the lock screen, and play sounds, your app must first request permission from the user. On iOS, Android, Huawei, Amazon, and Web, this involves displaying a system-level permission prompt.
iOS and Android system-level push permission prompts side by side
This guide is for mobile app push subscribers. For web push, see Web push permission prompts. Prerequisites: A OneSignal account, a mobile app with the OneSignal SDK installed, and in-app messages enabled.
iOS allows the system permission prompt only once. Android allows it twice. If the user declines, they must manually enable notifications in system settings. A poorly timed prompt can permanently cost you a subscriber.
On iOS, you can also use provisional notifications, which deliver quietly to the Notification Center without prompting the user — ideal for testing or low-friction onboarding.
Because the system prompt is limited, both Apple and Google strongly recommend explaining the value of your notifications before showing it. You can trigger the prompt at any time using the requestPermission() SDK method, but without proper context, users are more likely to decline — and on iOS, a declined prompt cannot be shown again. The recommended approach is a “soft prompt” — a custom in-app message that introduces the request before the system prompt. If the user accepts, the system prompt appears. If they decline, nothing happens and you can ask again later.
In-app message leading to system 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.
OneSignal in-app messages list showing the Push Permission Prompt template
Set the audience to Show to all users. OneSignal automatically filters this message to only show to users who haven’t subscribed to push, based on the Push Permission Prompt click action.
Audience setting configured to show to all users
3

Customize the message design

Personalize the look, feel, and wording to fit your app. 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.
In-app message block editor with a push opt-in prompt
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 appears.
Click action dropdown with Push Permission Prompt selected
iOS native push notification permission prompt
If a user has already denied permission, the button directs them to your app’s notification settings instead.
In-app messages with a Push Permission Prompt action are not 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 appears.
In-app message trigger configuration panel
You can trigger the message:
  • On app open
  • After a set amount of session time
  • On a specific user event
  • Programmatically, using the in-app message SDK methods for full control over timing and context
For example, to wait until the user has spent at least 5 minutes in the app:
Session duration trigger set to 5 minutes
6

Schedule and frequency

Control how often the message appears:
  • Only once — Low chance of converting users who weren’t ready the first time.
  • Every time conditions are met — Too aggressive and may annoy users.
  • Multiple times (recommended) — Set a high max (e.g., 9999) with a gap between views (e.g., 2 weeks). This re-prompts unsubscribed users periodically without being intrusive. Adjust the gap based on your use case.
Schedule configuration showing max displays and gap between views
Update your message and set it live. Monitor your stats and adjust the gap between displays as needed.

​
Programmatically show the permission prompt

You can trigger the push permission prompt manually using the requestPermission() or optIn() SDK methods. This is useful 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. If the in-app message displays but the user doesn’t tap the button, use the in-app message lifecycle events to track impressions and dismissals. To track the result of the system-level permission prompt itself, use the push permission listener.
You can send these SDK events to your backend or analytics tool of choice.

​
FAQ

​
What happens if a user denies the push permission prompt?

On iOS, denying the system prompt permanently disables push notifications for your app — the prompt cannot be shown again. On Android, the user gets one more chance (two total). After all attempts are used, the user must re-enable notifications manually in Settings > Notifications on their device. The OneSignal SDK’s requestPermission(fallbackToSettings: true) method can redirect users to their notification settings if permission was previously denied.

​
Can I customize the native system permission prompt?

No. The native iOS and Android permission dialogs are controlled by the operating system and cannot be customized. You can only control the soft prompt (the in-app message shown before the system prompt). Use the soft prompt to explain the value of your notifications, set expectations, and increase the chance of an “Allow” on the system prompt.

​
Can I still prompt users who have provisional notifications?

Yes. If you use iOS provisional push notifications, you can still show a soft prompt to convert those users to full push subscribers. Time the prompt strategically — after the user has seen value from your provisional notifications.

​
How do I re-prompt users who previously denied push?

You cannot show the system permission prompt again once the user has declined on iOS (or twice on Android). Instead, use the requestPermission(fallbackToSettings: true) SDK method, which opens the app’s notification settings page so the user can enable notifications manually. Pair this with an in-app message explaining why notifications are valuable.

​
When did Android start requiring permission prompts?

Android 13 (API level 33) introduced the runtime notification permission, requiring explicit user consent for push notifications.

iOS provisional push notifications

Send notifications to the Notification Center without an upfront permission prompt on iOS 12+.