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 refers to asking permission from your users 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.

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.

Browsers Are Changing How Notification Permission Prompts Work.

Chrome, Firefox and Safari are changing how prompting works. 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.

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.

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

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 Soft 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 - In early 2020, some major changes are happening. These are still being experimented on and you can read more about these changes in our blog

Currently, 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:

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

How can I translate the OneSignal Prompts?

Using 1 Language:

To translate the OneSignal prompts, you can add the language you want directly into the setup configuration.

Multiple Language Sites:

We currently do not have a way to change the OneSignal prompt's language automatically. The Native Permission Prompt will automatically be translated based on the user's browser language settings and cannot be customized.

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.

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 on this with example code:

Why is my prompt not showing?

Usually this happens if you do not have a prompt setup. Make sure to follow the prompting guide based on the prompt you want to use for your setup.

Otherwise, the most common reason is Auto-prompt (Immediately show prompt) is turned off in the Prompt Editor:

Make sure to turn it on, then press "Save" in the prompt Editor and "Save" again on the next page.

Can I add a delay to the prompt?

Yes! If you use Typical Setup, make sure to disable Auto-Prompt for both Slide and Native prompts.

Here is an example of how to add a delay based on time or 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?

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:

Updated 12 days 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.