Web permission prompts
Learn how to use OneSignal’s web push permission prompts to increase push notification opt-ins. Covers soft prompts, native browser prompts, slidedown prompts, category setup, email and phone number collection, and subscription bell customization.
Overview
“Prompting” refers to the process of asking users for 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 and receive push notifications.
Web Push works on Desktop, Android and iOS, but please note that web push for iOS requires some additional steps to configure. If you have a mobile app, see how to prompt for Push Permissions with In-App Messages.
Browsers provide their own native, system-level 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 is encouraged.
OneSignal prompts (soft prompts)
OneSignal soft prompts are user-friendly, customizable prompts that appear before the browser’s native permission dialog. These prompts do not subscribe users to notifications by themselves; instead, they help:
- Explain the value of subscribing to notifications (push, email, or SMS).
- Prevent browsers from automatically blocking permission requests.
- Launch the native browser prompt only after the user expresses interest.
Soft prompts are recommended by browsers and help maximize opt-in rates while protecting your domain reputation.
Prompt icon
To customize the icon shown in your web push notifications, go to your OneSignal dashboard: Settings > Push & In-App > Web Settings.
In the Site Setup section, configure the Default Icon URL. This icon appears in all your notifications unless otherwise specified.
- Accepted formats:
.pngor.jpg - Recommended size:
256x256pixels (to meet Safari’s requirements) - If left unset, OneSignal will use a generic bell icon
This setting can be changed at any time.
Image shows the Site Setup section of your web push settings. This is where you configure your website name, site URL, and default icon.
Permission prompt setup
Configure the prompts you’d like to display on your site to encourage user subscriptions. In your OneSignal dashboard, navigate to: Settings > Push & In-App > Web Settings > Permission Prompt Setup
From there, click Add Prompt to choose from OneSignal’s available prompt types. You can also edit any existing prompts already shown in the list.
Add new prompts or select the prompt you want to edit.
Each prompt type has different use cases and display behaviors. You can use them individually or in combination to guide users through the subscription process in a way that fits your website’s UX.
Available prompts are:
- Slidedown: A visually prominent prompt used for push notifications and optional category selection.
- Email/Phone prompt: Used to collect user email addresses, phone numbers, or both.
- Subscription bell prompt: A persistent floating widget for push subscriptions, typically placed in the bottom corner of your site.
- Custom link prompt: A customizable button or link embedded in your site that triggers the native browser prompt.
- Native permission prompt: The required browser-level prompt that must be accepted for users to receive push notifications.
Slidedown & category
The Slide and Category prompts appear prominently at the top center of the screen on desktop and bottom center on mobile. These are high-visibility, soft prompts shown before the required native permission prompt. They do not subscribe the user on their own but help initiate the subscription flow.
Example showing the Slide Prompt with Category Tags.
To add a Slide Prompt:
- Go to Settings > Push & In-App > Web Settings > Permission Prompt Setup
- Select Add Prompt > Push Prompt > Push Slide Prompt
For Custom Code setup, within your OneSignal init code’s promptOptions object. Use the slidedown properties. See Web SDK Reference for more details.
The push slide prompt options.
Slide prompt text
You can customize the text displayed in the slide prompt:
- Action message: up to 90 characters
- Button labels: up to 15 characters each
- Customization of font, size, or colors is not currently supported
Enable the text customization option in the dashboard. If no text is entered, default text will be used.
Slide prompt text options.
When finished, click Done and Save again on the next page to see this go into effect.
For Custom Code setup, within your OneSignal init code’s promptOptions object. Use the text properties. See Web SDK Reference for more details.
Categories
You can enhance the Slidedown prompt by adding categories—checkboxes that let users indicate interest in specific message topics (e.g., News, Sales, Updates).
- Up to 10 categories allowed
- Each category is stored as a Data Tag with a 1 (selected) or 0 (not selected)
- Useful for segmentation and targeting messages by user preferences
You may display the category prompt again later to let users update their preferences. Previously selected values will be retained unless overwritten.
- Label: what the user sees in the prompt. Recommended to capitalize the first letter.
- Tag Key: what the tag in OneSignal will be. Recommended to use lower case and underscores (
_) for spaces. - Update Instructions, Positive and Negative Buttons: if you choose to display the category prompt again after the user is already subscribed to push, the update instructions will be shown instead of the action message. This allows you inform the user they can update their categories.
Example categories. The Label is what users see while the tag key is what gets set as a tag key with a value of "1".
When finished, click Done and Save again on the next page to see this go into effect.
For Custom Code setup, within your OneSignal init code’s promptOptions object. Use the categories properties. See Web SDK Reference for more details.
Email & phone number prompt
The Email & Phone Prompt collects optional user contact information directly within a Slidedown. Each field has built-in validation to ensure correct formatting.
Once submitted:
- New Email and/or SMS subscriptions are created for the user
- You can start messaging them across these channels
To add this prompt:
- Navigate to Settings > Push & In-App > Web Settings > Permission Prompt Setup > Add Prompt > Email/Phone Prompt.
Email & Phone Number Prompt Setup
Customize which input fields are shown, the text labels, and the auto-prompt delay.
Email & Phone Number Prompt Setup
When finished, press Done and Save again on the next page to see this go into effect.
For Custom Code setup, within your OneSignal init code’s promptOptions object add the type to be either email, sms, or smsAndEmail. See Web SDK Reference for more details.
Subscription bell prompt
The Subscription Bell Prompt is a small, persistent widget that appears in the bottom corner of your website. When clicked by an unsubscribed user, it triggers the Native Browser Prompt.
Because of its minimal footprint, the bell can be left visible at all times, making it a passive yet effective option for ongoing opt-in opportunities. It does not require dismissal and provides users with control over when to subscribe.
Subscription Bell Prompt
You can customize the OneSignal Bell Prompt’s color, size, bottom position, text and more! 🛑 You cannot currently change the icon image or place the bell in the top corners.
Typical Site & WordPress Setup: Subscription Bell Prompt
Typical Site & WordPress Setup: Subscription Bell Prompt
Navigate to: Settings > Push & In-App > Web Settings > Permission Prompt Setup > Add Prompt > Subscription Bell Prompt
You can customize the bell’s:
- Color
- Size
- Bottom position (left or right)
- Text and labels
After setup, click Done, then Save to apply changes.
Subscription Bell Setup in Dashboard
Custom Code Setup: Subscription Bell Prompt
Custom Code Setup: Subscription Bell Prompt
Use the notifyButton parameter in your web SDK initialization options. You may toggle between different examples for Bell Prompt customizations.
Hiding: To hide the subscription bell after a user subscribes or only show it on certain pages, be sure to return the value false or a Promise that resolves to the value false in the displayPredicate function during initialization. This function is evaluated before the subscription bell is shown. You may return any other value to show the subscription bell.
Custom link prompt
The Custom Link Prompt is a user-triggered button or link you can embed anywhere on your website. When clicked, it displays the Native Browser Prompt for push notifications.
Custom Link Prompt
Common use cases:
- Below a blog post: “Like this article? Get updates as soon as we post!”
- In your site footer
- In a sticky header or floating toolbar
Typical Site & WordPress Setup: Custom Link Prompt
Typical Site & WordPress Setup: Custom Link Prompt
Navigate to: Settings > Push & In-App > Web Settings > Permission Prompt Setup > Add Prompt > Custom Link.
Add the provided HTML on your page where you want the widget to render.
Configure your options, then click Done and Save to activate.
Custom Link Setup in Dashboard
Custom Code Setup: Custom Link
Custom Code Setup: Custom Link
Within your OneSignal init code’s promptOptions object, add the customlink object and its available properties.
To render the prompt on your site, insert the following HTML where you want the widget to appear:
Typical & Custom Code Setup: Additional Styling
Typical & Custom Code Setup: Additional Styling
To change the appearance of the widget at any time all elements have a special class onesignal-reset that removes any prior styling from the element to make sure there are no conflict with our internal styles and that it looks exactly as you’ve defined it in the dashboard.
If you ever find yourself in need to redefine any OneSignal styles, here is a short reference of the classes used in the Custom Link widget
| Class Name | Applies to |
|---|---|
| onesignal-customlink-container | Main container |
| onesignal-customlink-subscribe | Action button |
| onesignal-customlink-explanation | Paragraph with a custom explanation text |
| state-subscribed | All components internal to the main container |
| state-unsubscribed | All components internal to the main container |
| button | Action button if in button mode |
| link | Action button if in link mode |
| small | All components internal to the main container |
| medium | All components internal to the main container |
| large | All components internal to the main container |
| hide | All components internal to the main container if unsubscribeEnabled is set to false |
To override any of them you have to create a CSS rule with higher specificity, combining the class name with the parent element id should be enough. But beware of the conflicts, our internal styles may change.
Native permission prompt
The native permission prompt is the browser-controlled dialog that users must accept to subscribe to push notifications from your website. This prompt is:
- Required for subscription
- Automatically triggered after OneSignal soft prompts (like a Slidedown or Custom Link)
- Not customizable in appearance, text, or behavior
Native Permission Prompt
Browser native prompt behavior
Different browsers impose unique behaviors and restrictions to reduce spammy permission requests:
Chrome
Chrome 80+ may display a quieter UI instead of the full prompt:
- Automatically applies to users who frequently deny prompts
- Also applies to sites with a high rate of denials
Chrome implements back-off logic if the user clicks the “X” on the native prompt:
- You have 3 attempts to prompt
- After the 3rd dismissal, the prompt is suppressed for 7 days (source).
Firefox
- Firefox 72+ requires a user gesture to trigger the prompt
- Auto-prompts are blocked, and users must actively interact with a site element
Safari
- Safari 12.1+ prompts require a user gesture
- Auto-prompting is silently blocked unless triggered by a direct interaction
Edge
Edge uses a trust-based model:
- If the site is untrusted, the prompt is suppressed and replaced by a bell icon in the browser bar:
Bell icon shown for unfamiliar or untrusted sites in Edge.
- If the site is trusted, the native prompt appears normally:
Native prompt appears directly for trusted sites in Edge.
Auto prompt & display settings
To maximize engagement and avoid disrupting your users, it’s best to delay showing prompts until after they’ve spent some time on your site. OneSignal allows you to automatically display prompts based on user behavior using two delay conditions:
- Page Views: Number of times the user loads any page on your site
- Seconds on Page: Amount of time the user must spend on the page
These delays are applied using an AND condition, meaning both must be satisfied before the prompt appears.
Example: If you set the delay to 3 page views and 30 seconds, the prompt will display on the third page load, after 30 seconds have passed. If the user doesn’t interact with the prompt, it will continue showing on each page load (after 30 seconds) until it’s clicked or dismissed.
Typical Site & WordPress Setup: Auto Prompt
Typical Site & WordPress Setup: Auto Prompt
- Navigate to: Settings > Push & In-App > Web Settings > Permission Prompt Setup
- Choose a prompt or create a new one
- Enable Auto Prompt
- Set your delay preferences (page views and time delay)
Example: This prompt is set to appear on the third pageview after 30 seconds.
- Click Done, then Save
If you want to trigger the prompt programmatically, keep Auto Prompt disabled and use the Web SDK Prompt prompt methods.
Custom Code Setup: Auto Prompt
Custom Code Setup: Auto Prompt
Within your OneSignal init code’s promptOptions object use the autoPrompt and delay options. There are also methods to trigger the desired slidedown or native prompts directly. See Web SDK Reference for more details.
Manual Triggering (Instead of Auto Prompt)
Manual Triggering (Instead of Auto Prompt)
If you want more control over when prompts are shown—for example, only on specific pages or after specific actions:
- Disable Auto Prompt
- Use the SDK’s Slidedown or Native Prompt methods to show the prompt via code
Slidedown prompt back-off logic
Once a Slidedown (Push, Category, or Email/Phone) prompt is shown and dismissed (via Allow, Cancel, or closing the dialog), it will back off and reappear on a defined schedule:
| Interaction Outcome | Next Prompt Timing |
|---|---|
| First Dismissal | Wait 3 days |
| Second Dismissal | Wait 7 days |
| Third and later dismissals (not subscribed) | Wait 30 days |
For example, if the user clicks “Allow” on the Slidedown but then clicks “X” on the browser’s native prompt (without subscribing), the Slidedown will follow the back-off cycle above.
If the user clears cookies or browser data, the back-off cycle resets and the prompt may appear again as if for the first time.
FAQ
How to translate/localize the prompt?
How to translate/localize the prompt?
Currently you will need to select the Custom Code Setup. Then programmatically change the language of the prompts by detecting the user’s browser language and initialize the OneSignal SDK with different text(s).
The native Permission Prompt will automatically translate to the browser’s set language.
Can I AB Test Prompts?
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.
Can I segment subscriptions based on the page they subscribed?
Can I segment subscriptions based on the page they subscribed?
Yes! Please see our guide Auto-Segment By Subscription Page.
Can I change the bell icon?
Can I change the bell icon?
You cannot change the bell image, but you can change the colors, text and put it on the bottom left of bottom right of the page.
Can I change the categories based on page?
Can I change the categories based on page?
Yes! This will require using the Custom Code Setup and adding the categories through code based on the above setup configurations.
How to track Slide Prompt Events?
How to track Slide Prompt Events?
The OneSignal Web SDK has the Slide Prompt Event Methods to detect when it shows on the screen, when it is closed, and the “Allow” or “Cancel” action.
After dismissing a web push prompt, when is the prompt shown again?
After dismissing a web push prompt, when is the prompt shown again?
For OneSignal Prompts, see Slidedown prompt back-off logic.
For the native permission prompts, see Browser native prompt behavior.
How can I show the prompt on only certain pages?
How can I show the prompt on only certain pages?
You must disable the Auto Prompt option, then add the Slidedown prompt code to the specific pages you want the prompts to show.
If you are using the Bell prompt, it cannot be disabled at a page-by-page basis at this time.
Why do I see the Slide Prompt on Firefox when I want the Native Browser Prompt?
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:
Firefox icon
The user must click this icon to view the native Permission Prompt on Firefox. This is why we default to the Slide Prompt on Firefox because it 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 (don’t forget to press the Save button), then use the Web SDK requestPermission() method.
Why do I see the Slide Prompt on mobile when I want the native Permission Prompt?
Why do I see the Slide Prompt on mobile when I want the native Permission Prompt?
On December 5th 2017, Google changed how the native Permission Prompt looks on Chrome for Android. It is a very user-unfriendly pop-up that takes over the entire screen of your site. We deliberately added the double prompt on Android to prevent your users from having a bad experience on your site.
If you do not want to show the Slide Prompt, you must turn off the Auto Prompt switch in the Prompt Editor (don’t forget to press the Save button), then use the Web SDK requestPermission() method.
Why does the slide prompt keep showing up?
Why does the slide prompt keep showing up?
Make sure you are not in incognito mode, private browser mode or guest browser mode.
Why is my prompt not showing?
Why is my prompt not showing?
A browser’s native Permission Prompt may not show if one of these conditions is true:
- The browser prevented the prompt from showing.
- The user has already allowed notifications or already subscribed
- The user blocked notifications. If a user clicks “Block” (Chrome), “Don’t Allow” (Safari), or “Never Allow” (Firefox) they can never be prompted again and must subscribe through a multi-step process in the browser settings. This is why it is recommended to use the OneSignal Prompts.
- Auto Prompt is turned off and no call to
requestPermission(); - The native Permission 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).
- 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 or you are using our Web SDK to prompt users.
For iOS, there are some additional requirements to prompt users for their subscription. More information can be seen in the Mobile Web Push for iOS/iPadOS guide.
Last would be to follow these steps to reset your cookie and browser cache to visit your site like a first-time user.