> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Prompt for push permissions
> Ask users for push notification permission at the right moment using in-app soft prompts and the native system prompt on iOS and Android.
## Overview
A push permission prompt is the operating system dialog shown when asking users whether your app can send notifications. The user's answer determines whether your app can deliver push notifications that appear as banners, show on the lock screen, and play sounds.
The system permission prompt can only be shown a limited number of times. iOS allows it **once**; Android allows it **twice**. If the user declines all attempts, they must manually enable notifications in system settings — a poorly timed prompt can permanently cost you a subscriber!
Both [Apple](https://developer.apple.com/design/human-interface-guidelines/managing-notifications) and [Google](https://developer.android.com/training/permissions/requesting) recommend explaining the value of your notifications before requesting permission. Without context, users are more likely to decline — and on iOS, a declined prompt cannot be shown again.
### Two ways to trigger the system prompt
You have two options for showing the system permission prompt with the OneSignal SDK. Most apps should start with the in-app message approach.
| Option | How it works | When to use |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **In-app message (recommended)** | Configure a OneSignal in-app message — a "soft prompt" — with a **Push Permission Prompt** click action. If the user taps the button, the system prompt appears. If they dismiss the in-app message, nothing is consumed and you can ask again later. | The default choice. Lets you design, schedule, target, and re-show the prompt without a code release. |
| **Programmatically from your app** | Call [`requestPermission()`](./mobile-sdk-reference#requestpermission-fallbacktosettings-push) or [`optIn()`](./mobile-sdk-reference#optout-optin-optedin) directly from your code. The system prompt appears immediately. | Custom flows where the trigger is owned by your app — preference centers, profile screens, in-app events that warrant a prompt. |
Both options end with the same system prompt; they only differ in what the user sees first. You can also combine them — for example, use a soft prompt at onboarding and a programmatic call from a preference center.
On iOS, you can also use [provisional notifications](./ios-provisional-push-notifications), which deliver quietly to the Notification Center without any prompt — ideal for testing or low-friction onboarding.
This guide covers mobile app push. For web push, see [Web push permission prompts](./permission-requests).
***
## Prerequisites
* A [OneSignal account](https://dashboard.onesignal.com).
* A mobile app with the [OneSignal SDK installed](./mobile-sdk-setup) and the `OneSignalInAppMessages` package enabled.
***
## Set up an in-app push permission prompt
Before you begin, make sure your app isn't already triggering the system permission prompt automatically:
* Remove any `requestPermission()` or `optIn()` calls invoked on app start.
* Remove native iOS calls to `requestAuthorizationWithOptions` and any code that generates push tokens directly.
* Remove Android calls to `requestPermissions` and any code that generates push tokens directly.
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**. OneSignal automatically filters this message to only users who haven't subscribed to push, based on the **Push Permission Prompt** click action.
Personalize the look, feel, and wording to fit your app. Tell users what kind of notifications they'll get and why they're valuable.
See [Design in-app messages with drag and drop](./design-your-in-app-message) or [Design in-app messages with HTML](./design-your-in-app-message-with-html) for details.
Add a **Push Permission Prompt** click action to any button or image in your message. When tapped, the system permission prompt appears.
If the user has already declined the system permission prompt the maximum number of times (once on iOS, twice on Android), the click action instead sends them to your app's notification settings. This is equivalent to calling `requestPermission(fallbackToSettings: true)` from the SDK.
In-app messages with a **Push Permission Prompt** click action are not shown to users who have already allowed notifications.
The audience controls *who* is eligible to see the message. Triggers control *when* it appears.
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 trigger SDK methods](./mobile-sdk-reference#addtrigger-addtriggers) for full control over timing and context.
For example, to wait until the user has spent at least 5 minutes in the app:
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 per user (for example, the maximum value of `9999`) with a gap between views (for example, `2 weeks`). This re-prompts unsubscribed users periodically without being intrusive. Adjust the gap based on your use case.
Set the message live, monitor your prompt-to-opt-in conversion in the message report, and adjust the gap between displays as needed.
***
## Programmatically show the permission prompt
You can trigger the system permission prompt manually using the [`requestPermission()`](./mobile-sdk-reference#requestpermission-fallbacktosettings-push) or [`optIn()`](./mobile-sdk-reference#optout-optin-optedin) SDK methods. This is useful for custom flows such as:
* A [preference center](./preference-center).
* A user profile screen.
* Specific in-app events.
Pass `fallbackToSettings: true` to `requestPermission()` so that users who have already declined are redirected to the app's notification settings instead of silently doing nothing.
If a subscription has been opted out at the SDK level via `optOut()` (shown as `notification_types: -2` on the subscription record), `requestPermission()` alone will not change the subscription status. Use `optIn()` instead — it requests permission **and** clears the opt-out state.
***
## Track push permissions and prompt results
* Track which button the user tapped in the soft prompt with the [in-app message click listener](./mobile-sdk-reference#addclicklistener-in-app).
* Track impressions and dismissals (when the user sees but doesn't tap the soft prompt) with the [in-app message lifecycle listener](./mobile-sdk-reference#addlifecyclelistener).
* Track the result of the system permission prompt itself with the [push permission observer](./mobile-sdk-reference#addpermissionobserver-push).
You can forward these SDK events to your backend or analytics tool of choice.
***
## FAQ
### What happens if a user denies the system permission prompt?
On iOS, denying the system permission 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 [`Push Permission Prompt` click action](#add-the-push-permission-prompt-click-action) and [`requestPermission(fallbackToSettings: true)`](./mobile-sdk-reference#requestpermission-fallbacktosettings-push) both handle this by sending the user directly to their notification settings.
### Can I customize the native system permission prompt?
No. The system permission prompt on iOS and Android is controlled by the operating system and cannot be customized. You can only customize the soft prompt (the in-app message shown before it). 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](./ios-provisional-push-notifications), you can still show a soft prompt to convert those users to full push subscribers. Time the prompt for a moment when the user has just seen value from a provisional notification — for example, right after they open a notification or act on it.
### How do I re-prompt users who previously denied push?
Once the system permission prompt has been exhausted (once on iOS, twice on Android), you cannot show it again. Instead, use the [`requestPermission(fallbackToSettings: true)`](./mobile-sdk-reference#requestpermission-fallbacktosettings-push) SDK method or the **Push Permission Prompt** click action on an in-app message — both open your app's notification settings so the user can enable notifications manually. Pair this with an in-app message explaining why notifications are valuable.
### Do all Android versions require a system permission prompt?
No — only Android 13 (API level 33) and later. Android 13 introduced the runtime notification permission, requiring explicit user consent for push notifications.
* **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](https://developer.android.com/develop/ui/views/notifications/notification-permission).
On Android 12 and lower, the app is granted notification permission automatically on install.
***
Send notifications to the Notification Center without an upfront permission prompt on iOS 12+.
`requestPermission`, `optIn`, permission observer, and in-app click listener APIs.
Configure soft-prompt, slide-down, and native web push permission requests.
Enable in-app messaging in your app so you can run soft prompts.