OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions


Concepts - Prompts & Permission Requests

Asking permission to send push notifications is one of the most important things your app or website can do. Getting permission means you have a channel with which to reach and re-engage your users, improving their experience and the value of your product. This is why how you ask for permissions is a crucial design decision for your app or website.

What are Prompts & Permission Requests?

iOS, Android, Web Push (Chrome, Firefox, Safari)

Permission Prompts are custom messages that a developer can present to users prior to triggering the Permission Request of the device / browser. In the following example the Prompt is on the left, and a Permission Request is on the right:

Using permission prompts prior to permission requests is a best practice in both mobile and web push, because they increase the likelihood users will stay subscribed to your push notifications and find value in them. Permission prompts do three things:

  1. Inform a user of the value of subscribing to push notifications.

  2. Capture user intent with buttons like 'Sure' and 'Not Now'.

  3. Trigger a Permission Request, if users indicate intent.

Prompts are a 'soft request', meaning that they are not invoking the 'hard request' of the system Permission Request dialog. This is important because if a user denies a system Permission Request, the developer is unable to prompt the user again, unless the user goes through an multi-step process to re-enable these permissions. On the other hand, if a user dismisses a Prompt, the app or website can still present them the option later on.

User Allows
User Doesn't Allow


Trigger Permission Request

Let user continue on

Permission Request

Push Permission Granted

Push Permission Denied, app no longer able to trigger Permission Request

OneSignal Prompts

iOS, Android - OneSignal does not currently offer pre-made prompts for mobile apps. However you may design your own, and use the OneSignal API to trigger Permission Requests if the user taps to agree to your message. Note: Android does not require a prompt for mobile apps. Users get subscribed when they download and open the app the first time. You can prevent our SDK from loading following our Handling Personal Data Guide.

Web Push (Chrome, Firefox, Safari) - OneSignal offers the below pre-made prompts, which may be triggered automatically upon arrival to your site, or programmatically at a time of your choosing. You may also design your own using the OneSignal API.

HTTP Pop-Up Prompt

Web Push (Chrome, Firefox, Safari)

HTTP only - The HTTP Pop-Up Prompt is presented in a separate pop-up window for HTTP sites. Learn more about HTTP Pop-Up Prompt

Slide Prompt

Web Push (Chrome, Firefox, Safari)

The Slide Prompt displays on top of your site, in the top center of the browser (bottom center on Android). Learn more about the Slide Prompt

Subscription Bell

Web Push (Chrome, Firefox, Safari)

The subscription bell is a small widget that resides in the lower left corner of your site, which users can click to bring up the Permission Request for your site. It is designed to be small enough that you may keep it on your site at all times, and does not require users to dismiss it (like the above designs). Learn more about the Subscription Bell

Custom Link

Web Push (Chrome, Firefox, Safari)

Simply add a snippet to your site's markup and it will be rendered as a button or link that triggers subscription flow when user chooses to subscribe. Provides good user experience. Can be customized through the dashboard at any time without changes to your site's code. Learn more about Custom Link

Native Browser Prompt

HTTPS Web Push (Chrome, Firefox)

HTTPS sites may choose not to use a prompt and instead trigger the browser's native permission request by following this tutorial: Trigger Browser Permission Request


How do I ask an iOS user to activate notifications later if they've already chosen NO the first time they were asked?

The user will have to turn on notifications for your app in their device settings.

It's not possible to show the prompt again, but some apps show a guide on how to enable notifications in the device settings. One common practice is to have your app show its own dialog first asking if a user wants notifications, and have them select "yes", before showing the native one. That way you don't lose your chance to show them the native prompt if they decide to change their mind later.

After dismissing a web push prompt, when is the prompt shown again?

Native Browser Prompt:

You have 3 tries to get the user to subscribe, after the 3rd "X" click on the required native browser prompt, they will not get prompted again for a week. More on this Chrome feature here

OneSignal Soft Prompts:

By default, after dismissing a OneSignal prompt, a web push prompt won't be shown for the next 3 days initially. After 3 days when the prompt is shown again, if the prompt is dismissed again then it won't be shown for the next 7 days. After 7 days elapse, if the prompt is dismissed again it won't be shown for the next 30 days. Subsequent dismissals will also hide the prompt for 30 days.

The above are our defaults to maintain a good user experience. You may customize and show the prompt at any time using our showHttpPrompt() Web Push SDK.

For testing purposes, please follow Clearing your cache and resetting push permissions to access your site as a new first-time user.

What are some best practices around Web Push Prompting?

It is best to ask someone to subscribe after you have provided some value to them through the site.

A common best practice for web push prompting is to show the OneSignal Slide prompt first along with the OneSignal Bell or Custom Link.

This way, if a user dismisses the Slide Prompt, they can still subscribe through the OneSignal Bell or Custom Link.

You can add a delay to the Slide Prompt

Can I add a delay to the prompt?

Yes, you can add a delay to the prompt but this requires the Custom Code Setup

Here is an example of how to add a delay based on time

Example of how to delay based on X visits

WordPress Users: this requires some Custom Code Setup and this guide on adding a delay to your WordPress Site

How can I show the prompt on only certain pages?

To prompt whenever you like or only on certain pages, simply add the setup code we provide you for the Typical Setup or Custom Code Setup to the pages you want to show the prompts on.

Using the Custom Code Setup you can setup the OneSignal init code on all pages but use specific triggers to call the prompt when you like. See the prompts above for more details.

For WordPress, there is currently not a way to disable the OneSignal subscription prompts on certain pages/posts through the plugin directly.

You will need to add some custom code to do this.

Here is our guide with 2 different options on how to setup the prompts differently on different pages of your site:

How can I translate the OneSignal Prompts?

To translate the OneSignal prompts, you can add the language you want directly into the setup configuration for the Typical Setup or Wordpress Plugin. If you use the Custom Code Setup you can add the language directly into the init code. More on this in our Web Push Examples guide.

We currently do not have a way to change the OneSignal prompt's language depending on the browser language. However, there are a couple options you can do to work around this:

1 - If you use a OneSignal prompt, like the Slide or Bell Prompt, you can use the Custom Code Setup Setup and initialize OneSignal with the language you detect on your site. Here is a Stackoverflow if you need assistance detecting browser language.

2 - if you have an HTTPS site, you can use the Native Browser Prompt, which will translate to the browser settings. This will not work with the OneSignal prompts, like the Bell or Slide.

Why does my Prompt keep showing up?

Make sure you are not in incognito mode, private browser mode or guest browser mode.


Concepts - Prompts & Permission Requests

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.