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

Prompting is asking user's permission to send them push notifications. Prompts are pop-up messages presented by the browser or mobile app and require the user to click "Allow" to be subscribed.

Prompting users effectively is the first step to gaining more subscribers.

If you have a mobile app, see our iOS Prompt Guide. Android Mobile App devices don't need to be prompted, they get subscribed when opening your app for the first time.

Web Prompting Overview

Each browser provides its own Native Permission Prompt which is required to be both shown and clicked "Allow" for the user to subscribe to your website.

Browsers now highly recommend websites be more selective when it comes to showing the Native Permission Prompt. This is why using OneSignal Prompts or your own custom "soft prompts" before the native prompt are encouraged.


Browser Changes to Notification Permission Prompts

Chrome, Firefox and Safari have changed how prompting works. If you trigger the Native Permission Prompt, you may see the following changes:
Chrome 80+ adds a quieter UI for prompting users who typically deny permissions and automatically for sites that get denied for push more frequently.
Safari 12.1+ and Firefox 72+ add the requirement for a "user gesture" (clicking a button) before the native prompt is shown.

Read more about these changes and best practices in our blog post: Browsers Are Changing How Notification Permission Prompts Work.

OneSignal already provides what you need to stay ahead of these changes with our OneSignal Prompts and the ability to show these prompts at relevant moments.

OneSignal Prompts

OneSignal provides "soft prompts" that are shown before the Native Permission Prompt and engage the user to take action. They do not replace the native prompt and do not subscribe the user to web push.

These prompts are beneficial because they increase the likelihood users will stay subscribed to your push notifications and are highly recommended by the browsers. Permission prompts do three things:

  1. Inform a user of the value of subscribing to push notifications.
  2. Prevent users from being blocked from subscribing.
  3. Trigger a Native Prompt, if users indicate intent.

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

Delayed Prompts

Asking users for push permission once they've read content on your site for a period of time or navigated through a few pages can improve opt in rate, and ensure that your opt-in rates remain high (some browsers penalize low opt in rates to push by hiding the push prompt).

Using the OneSignal Typical Site Setup you can customize showing the Slide or Native prompt after X amount of seconds the user is on the site and/or after X amount of page views. For example, prompt the user after 30 seconds after visiting 3 pages.

If you are using Custom Code Setup, see examples for configuring prompt delays through OneSignal init. WordPress requires some more steps shown in this guide on adding a delay to your WordPress Site.

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).

Category Slidedown

Web Push (Chrome, Firefox, Safari)

The Category Slidedown works just like the regular Slide Prompt except it also allows subscribers to opt-in or out of notification categories. The Category Slidedown is configurable through the dashboard for Typical Site setup in the same place as the Slide Prompt. Simply click on the toggle for Categories to turn on this feature. It can also be configured via custom code OneSignal implementations.

Learn more about Category Slidedown

Subscription Bell

Web Push (Chrome, Firefox, Safari)

The subscription bell is a small widget that resides in the lower left or right corner of your site, which users can click to bring up the Native Permission Prompt 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.

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.

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. It cannot be triggered alone and must follow the above prompts.

Native Permission Prompt

HTTPS Web Push (Chrome, Firefox)

HTTPS sites may choose not to use a soft prompt and instead trigger the browser's Native Permission Prompt. However, immediately prompting users to subscribe with the Native prompt is being deprecated by the browsers and is not recommended.


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

If a user clicks "Block" (Chrome), "Don't Allow" (Safari), or "Never Allow" (Firefox) on the Native Permission Prompt they can never be prompted again and must subscribe through a multi-step process through the browser settings. This is why it is recommended to use the OneSignal Prompts.

If a user clicks "X" on Chrome or Safari Native Permission Prompt or "No" on the OneSignal Prompts, then the following occurs:

Native Permission Prompt:

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

Firefox - Beginning with Firefox 70 once a user clicks "X" they will need to click the small notification icon in the browser to be prompted again.

OneSignal Soft Prompts:

The OneSignal Side Prompt will show after 3 days, 7 days, then 30 days if the user clicks "Allow" or "Cancel" on it and is still not subscribed.

For instance, if a user clicks "Allow" on the slide prompt, but "x" on the native prompt, it will not show again for 3 days the first time. After 3 days, it will show again and if the user clicks "Cancel" or "Allow" but "X" on the native prompt, it will not show again for 7 days. After 7 days if the user does this again, it will be every 30 days.

If the user clears cookies or browser data, the cycle resets.

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 visitors to subscribe after you have provided some value to them through the site. This could be after they have read your articles, on site settings or profile pages, and/or in your shopping-cart or check-out flow.

Common best practices include:

  1. Using a Delayed Slide Prompts after 2 page visits and 20 seconds have passed.
  2. Embedding the Custom Link prompt in the middle and/or at the end of the articles and within a "Subscription Page" or section of the user's Profile page if you have one.
  3. Adding the Bell Prompt to allow users to easily subscribe/unsubscribe throughout the site.
  4. If you add your own call-to-action buttons (like add to cart or subscription events) on the site or want to show the Native Browser Prompt anytime, use the OneSignal.showNativePrompt(); method. Your site must be HTTPS and did not select "My site is not fully HTTPS" in the OneSignal Site configuration.

How can I translate the OneSignal Prompts?

You can put whatever language you like into the prompt. If you are trying to dynamically change the prompt language based on the page, then that will require switching to the Custom Code Setup and initialize OneSignal based on the language of the page.

Currently OneSignal does not automatically translate the Slide Prompt , Bell Prompt , or Custom Link prompt. They default to English, but you can put whatever language and message you want.

If you have an HTTPS site and did not select "My site is not fully https" in the setup, you can use the Native Browser Prompt, which will translate to the browser language settings.

Can I AB Test Prompts?

Using the Custom Code Setup you can initialize OneSignal with the different prompting options. You would need to setup your own way to trigger the A/B/C/D etc tests which initialize OneSignal.

As a bonus, you can use the Subscription Change method to detect when the user subscribed and add Data Tags based on which test won the subscription.

Why does my Prompt keep showing up?

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

Can I segment users based on the page they subscribed?

Yes! Please see our guide Auto-Segment By Subscription Page.

Why is my prompt not showing?

The Native Browser Prompt will not show while in Incognito Mode, Private Browser mode or Guest Browser mode. It will also not show right away on Safari 12.1+ or Firefox 72+ (more details).

Also make sure you are using a browser and device that supports web push.

Check your prompt setup to make sure Auto-prompt is turned on and the Delayed Prompts are not blocking you.

Last would be to follow these steps to reset your cookie and browser cache to visit your site like a first time user.

How can I show the prompt on only certain pages?

If you use Typical Setup, make sure to disable Auto-Prompt for both Slide and Native prompts. If you use the bell prompt, you will need to remove the OneSignal init call on pages you do not want the bell to show or switch to the Custom Code Setup.

You can now trigger the Native or Slide prompt with the SDK methods. See the prompt guide for details.

WordPress Users: there is currently not a way to disable the OneSignal subscription prompts on certain pages/posts through the plugin directly, this will require adding code to the site.

We provide 2 options on how to setup the prompts on different pages of your site:

Why do I see the Slide Prompt on Firefox when I want the Native Browser Prompt?

With Firefox 72+ there is a change that requires a user to click a button to show the native browser prompt. If you try to automatically show the native browser prompt, you will see an icon within the browser like this:

The user must click this icon to view the Native Browser Prompt on Firefox. This is why we default to the Slide Prompt on Firefox because it is more "eye-catching" and requires the 2-step opt-in in either case.

If you do not want to show the Slide Prompt as default, you must turn off the "Auto-Prompt" switch in the Prompt Editor:

Press "Save" and "Save" again on the next page. You can then use the OneSignal.showNativePrompt() SDK method to trigger the Native Prompt on any page you want. Example code:

<script src="" async=""></script>
  var OneSignal = window.OneSignal || [];
  OneSignal.push(function() {
      appId: "3beb3078-e0f1-4629-af17-fde833b9f716",

Updated 2 months ago


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.