Web permission prompts

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: .png or .jpg
Recommended size: 256x256 pixels (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.

For details on triggering the prompt, see Auto prompt & display settings.

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.

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.

For details on triggering the prompt, see Auto prompt & display settings.

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

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.

// Your other init options here
notifyButton: {
    enable: true, /* Required to use the Subscription Bell */
    size: 'medium', /* One of 'small', 'medium', or 'large' */
    theme: 'default', /* One of 'default' (red-white) or 'inverse" (white-red) */
    position: 'bottom-right', /* Either 'bottom-left' or 'bottom-right' */
    offset: {
        bottom: '0px',
        left: '0px', /* Only applied if bottom-left */
        right: '0px' /* Only applied if bottom-right */
    },
    showCredit: false, /* Hide the OneSignal logo */
    text: {
        'tip.state.unsubscribed': 'Subscribe to notifications',
        'tip.state.subscribed': "You're subscribed to notifications",
        'tip.state.blocked': "You've blocked notifications",
        'message.prenotify': 'Click to subscribe to notifications',
        'message.action.subscribed': "Thanks for subscribing!",
        'message.action.resubscribed': "You're subscribed to notifications",
        'message.action.unsubscribed': "You won't receive notifications again",
        'dialog.main.title': 'Manage Site Notifications',
        'dialog.main.button.subscribe': 'SUBSCRIBE',
        'dialog.main.button.unsubscribe': 'UNSUBSCRIBE',
        'dialog.blocked.title': 'Unblock Notifications',
        'dialog.blocked.message': "Follow these instructions to allow notifications:"
    }
}

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

Custom Code Setup: Custom Link

Within your OneSignal init code’s promptOptions object, add the customlink object and its available properties.

// Your other init options here
promptOptions: {
  customlink: {
    enabled: true, /* Required to use the Custom Link */
    style: "button", /* Has value of 'button' or 'link' */
    size: "medium", /* One of 'small', 'medium', or 'large' */
    color: {
      button: '#E12D30', /* Color of the button background if style = "button" */
      text: '#FFFFFF', /* Color of the prompt's text */
    },
    text: {
      subscribe: "Subscribe to push notifications", /* Prompt's text when not subscribed */
      unsubscribe: "Unsubscribe from push notifications", /* Prompt's text when subscribed */
      explanation: "Get updates from all sorts of things that matter to you", /* Optional text appearing before the prompt button */
    },
    unsubscribeEnabled: true, /* Controls whether the prompt is visible after subscription */
  }
}

To render the prompt on your site, insert the following HTML where you want the widget to appear:

html

<div class='onesignal-customlink-container'></div>

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

Custom Code Setup: Auto Prompt

Manual Triggering (Instead of Auto Prompt)

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.

This logic applies to Push, Category, and Email/Phone Slidedown prompts. You can bypass the backoff logic using our Web SDK Slidedown prompt methods.For native prompt back-off logic, see Browser native prompt behavior. You cannot bypass the backoff logic for the native prompt because this is controlled by the browser.

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?

Can I AB Test Prompts?

Can I segment subscriptions based on the page they subscribed?

Can I change the bell icon?

Can I change the categories based on page?

How to track Slide Prompt Events?

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

How can I show the prompt on only certain pages?

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

Why do I see the Slide Prompt on mobile when I want the native Permission Prompt?

Why does the slide prompt keep showing up?

Why is my prompt not showing?

First steps & settings

Message channels

Journeys

Audience & custom events

Analytics & Integrations

Privacy & Security

Web permission prompts

Overview

OneSignal prompts (soft prompts)

Prompt icon

Permission prompt setup

Slidedown & category

Slide prompt text

Categories

Email & phone number prompt

Subscription bell prompt

Custom link prompt

Native permission prompt

Browser native prompt behavior

Chrome

Firefox

Safari

Edge

Auto prompt & display settings

Slidedown prompt back-off logic

FAQ

First steps & settings

Message channels

Journeys

Audience & custom events

Analytics & Integrations

Privacy & Security

​Overview

​OneSignal prompts (soft prompts)

​Prompt icon

​Permission prompt setup

​Slidedown & category

​Slide prompt text

​Categories

​Email & phone number prompt

​Subscription bell prompt

​Custom link prompt

​Native permission prompt

​Browser native prompt behavior

​Chrome

​Firefox

​Safari

​Edge

​Auto prompt & display settings

​Slidedown prompt back-off logic

​FAQ

Overview

OneSignal prompts (soft prompts)

Prompt icon

Permission prompt setup

Slidedown & category

Slide prompt text

Categories

Email & phone number prompt

Subscription bell prompt

Custom link prompt

Native permission prompt

Browser native prompt behavior

Chrome

Firefox

Safari

Edge

Auto prompt & display settings

Slidedown prompt back-off logic

FAQ