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    Support

Customize Permission Messages

Prompting users to opt-in to your notifications for Web Push (Chrome, Firefox, and Safari) notifications.

For Developers

To learn about Permission Messages and Permission Requests, including an overview and best practices, first read our feature overview of Permission Messages & Requests.

How to add custom Permission Messages

Web Push (Chrome, Firefox, and Safari)

OneSignal offers four Permission Message designs: Fullscreen, Slidedown, HTTP Permission Request Post Modal, and Subscription Bell. In addition, you may implement your own custom link, an example is below.

Triggering & Customizing Permission Messages

The following are ways to trigger and customize Permission Messages within OneSignal.

To create the most compelling messages for why users should subscribe to your push notifications, you need to customize your Permission Message content.
You may enter text in your own language, but please note all fields are limited in length (usually to one line of text). If you have chosen to implement a Custom Link (above), you may customize it any way you like.

Permission Message
Triggering Notes
Customizability Notes

HTTPS, HTTP - enabled by default.

Color and text

Wordpress - enabled by default.

Icon, text, and buttons

Disabled by default. May be triggered manually on page load.

Icon, text, and buttons

Create custom Permission Message.

Text

HTTP Only for HTTP sites and only enabled by setting httpPermissionRequest to be { enabled: true }.

Text and button

Subscription Bell

Trigger/Show Subscription Bell

Enabled through the example code we provide in our web push setup guides (HTTPS, HTTP).
Show: notifyButton: { enable: true }
Don't Show: notifyButton: { enable: false }

We do not currently support a way to manually show or hide the subscription bell.

Customize Subscription Bell

The colors and text of the Subscription Bell can be customized, however the icon itself cannot.

Wordpress - customizing all of the features below can be found on the Configuration tab of our plugin.

HTTPS, HTTP - Use the notifyButton parameter in your web SDK initialization options.

// Do NOT call init() twice
OneSignal.push(["init", {
    /* Your other init options here */
    notifyButton: {
        enable: true, /* Required to use the notify button */
        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 */
        },
        prenotify: true, /* Show an icon with 1 unread message for first-time site visitors */
        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:"
        }
    }
}]);
Customizing Subscription Bell Colors

You can override the theme's colors by entering your own. Values are strings which are then interpreted by CSS, so any CSS-valid color works as each value.
Examples: white, #FFFFFF, #FFF, rgb(255, 255, 255), rgba(255, 255, 255, 1.0), and transparent are all valid values.

// Do NOT call init() twice
OneSignal.push(["init", {
  // Your other init options here
  notifyButton: {
    enable: true, // Required to use the notify button
    // Your other notify button settings here
    colors: { // Customize the colors of the main button and dialog popup button
      'circle.background': 'rgb(84,110,123)',
      'circle.foreground': 'white',
      'badge.background': 'rgb(84,110,123)',
      'badge.foreground': 'white',
      'badge.bordercolor': 'white',
      'pulse.color': 'white',
      'dialog.button.background.hovering': 'rgb(77, 101, 113)',
      'dialog.button.background.active': 'rgb(70, 92, 103)',
      'dialog.button.background': 'rgb(84,110,123)',
      'dialog.button.foreground': 'white'
    },
  }
}]);
Hiding the Subscription Bell

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.

Here is an example hiding the subscription bell if the user is subscribed:

// Do NOT call init() twice
// This is just an example
OneSignal.push(["init", {
    /* Your other init options here */
    notifyButton: {
        /* Your other notify button settings here ... */
        enable: true,
        displayPredicate: function() {
            return OneSignal.isPushNotificationsEnabled()
                .then(function(isPushEnabled) {
                    /* The user is subscribed, so we want to return "false" to hide the notify button */
                    return !isPushEnabled;
                });
        },
    }
}]);

Slidedown Permission Message

Trigger/Show Slidedown Permission Message

Can be triggered any time via showHttpPrompt().

HTTPS - Set autoRegister: false
Can be triggered "automatically" if you call OneSignal.showHttpPrompt().
Note: the Slidedown message cannot replace the browser's native prompt.
The browser's native permission prompt must ALWAYS be shown before the user can subscribe.

HTTP - Set autoRegister: true
Automatically triggered when a user arrives to your website if you set autoRegister: true during initialization (see example code).
When users click 'Allow', this message triggers the browser's native permission prompt which must ALWAYS be shown before the user can subscribe.

Wordpress - Enabled by default, and can be turned off in the Configuration tab of the Wordpress plugin.

Note: there are several reasons why a user may not see the Permission Message, and why a user may see the Permission Message frequently.

Customize Slidedown Permission Message

HTTPS, HTTP - You may customize the text in the Slidedown Permission Message by including the contents in your initialization function:

// Do NOT call init() twice
OneSignal.push(["init", {
    // Your other init options here
    promptOptions: {
        /* These prompt options values configure both the HTTP prompt and the HTTP popup. */
        /* actionMessage limited to 90 characters */
        actionMessage: "We'd like to show you notifications for the latest news and updates.",
        /* acceptButtonText limited to 15 characters */
        acceptButtonText: "ALLOW",
        /* cancelButtonText limited to 15 characters */
        cancelButtonText: "NO THANKS"
    }
}]);

Wordpress - You may customize the text in the Slidedown Permission Message by following these steps:

  1. Visit the OneSignal Push page of our WordPress plugin, and click the Configuration tab.

  2. Visit the section titled Popup Settings.

  3. The fields Action Message, Accept Button Text, and Cancel Button Text are used for the drop-down prompt.

  4. The notification icon can be set from App Settings by clicking Configure next to the Google Chrome & Mozilla Firefox platform settings.

HTTPS, HTTP, Wordpress - You may customize the image shown in the Slidedown Permission Message by editing the Default Notification Icon URL in your dashboard:

If you do not have a Default Notification Icon URL set, OneSignal will show a generic icon.


Fullscreen Permission Message


Trigger Fullscreen Permission Message

You may create your own button or link that calls registerForPushNotifications() to trigger the Fullscreen Permission Message.

HTTPS - You may also programmatically trigger the Fullscreen Permission Message by passing the flag modalPrompt: true to the API call registerForPushNotifications().

HTTP - Due to browsers blocking popups, your site may not programmatically trigger the Fullscreen Permission Message. The Fullscreen Permission Message will appear as a pop-up window when users click either our Subscription Bell, or a button or link you create that triggers it.

Customize Fullscreen Permission Message

To customize the text, buttons, and images in the Fullscreen Permission Message, use the promptOptions parameter in your init() options. You may change all text except the URL on the notification image (subdomain.onesignal.com). You may enter text in your own language, but please note all fields are limited in length (usually to one line of text). Any fields you do not define will use their defaults.

// Do NOT call init() twice
OneSignal.push(["init", {
    // Your other init options here
    promptOptions: {
        /* Change bold title, limited to 30 characters */
        siteName: 'OneSignal Documentation',
        /* Subtitle, limited to 90 characters */
        actionMessage: "We'd like to show you notifications for the latest news and updates.",
        /* Example notification title */
        exampleNotificationTitle: 'Example notification',
        /* Example notification message */
        exampleNotificationMessage: 'This is an example notification',
        /* Text below example notification, limited to 50 characters */
        exampleNotificationCaption: 'You can unsubscribe anytime',
        /* Accept button text, limited to 15 characters */
        acceptButtonText: "ALLOW",
        /* Cancel button text, limited to 15 characters */
        cancelButtonText: "NO THANKS"
    }
}]);

Customizing "Click Allow": Set the autoAcceptTitle of promptOptions:

// Do NOT call init() twice
OneSignal.push(["init", {
    // Your other init options here
    promptOptions: {
        /* Change click allow text, limited to 30 characters */
        autoAcceptTitle: 'Click Allow',
        /* ... */
    }
}]);

Custom Link Permission Message

Trigger Custom Link Permission Message

Instead of using our pre-built templates, you may also choose to create your own Permission Message with a link.

HTTPS - this link prompts a Permission Request when clicked.

HTTP - this link prompts a pop-up window version of the Fullscreen Permission Message when clicked.

We highly recommend only showing this custom Permission Message and link if the user is unsubscribed. Below is an example of code that does this:

<body>
    <a href="#" id="subscribe-link" style="display: none;">Subscribe to Notifications</a>
    <script>
        function subscribe() {
            OneSignal.push(["registerForPushNotifications"]);
            event.preventDefault();
        }

        var OneSignal = OneSignal || [];
        /* This example assumes you've already initialized OneSignal */
        OneSignal.push(function() {
            // If we're on an unsupported browser, do nothing
            if (!OneSignal.isPushNotificationsSupported()) {
                return;
            }
            OneSignal.isPushNotificationsEnabled(function(isEnabled) {
                if (isEnabled) {
                    // The user is subscribed to notifications
                    // Don't show anything
                } else {
                    document.getElementById("subscribe-link").addEventListener('click', subscribe);
                    document.getElementById("subscribe-link").style.display = '';
                }
            });
        });
    </script>
</body>

HTTP Permission Request


Trigger HTTP Permission Request

The HTTP Permission Request, only for HTTP sites, may also be triggered by ensuring your OneSignal initialization configuration has the httpPermissionRequest property (see docs) and enabled: true in the property.

Customize HTTP Permission Request Post Modal

Only the second image (post modal) is customizable. To customize this post modal text, please use:

// Do NOT call init() twice
OneSignal.push(["init", {
    // Your other init options here
    httpPermissionRequest: {
        modalTitle: 'Thanks for subscribing',
        modalMessage: "You're now subscribed to notifications. You can unsubscribe at any time.",
        modalButtonText: 'Close'
        /* ... */
    }
}]);

If you don't want to use our modal and you want to display your own, this is also possible. Set useCustomModal to true:

// Do NOT call init() twice
OneSignal.push(["init", {
    // Your other init options here
    httpPermissionRequest: {
        /* Set useCustomModal to true to replace our post request modal with yours */
        useCustomModal: true,
        /* ... */
    }
}]);

You must display a modal after, and the user must click this modal to be fully subscribed. If the user does not click your custom modal, the user will not be subscribed. To use your own custom modal:

  1. Please use the notificationPermissionChange event to detect when the user accepts the browser's notification permission request.

  2. Display your own custom modal.

  3. Call OneSignal.registerForPushNotifications({httpPermissionRequest: true}) (note the special option name) when the user clicks. We recommend dimming the page and calling the register function if the user clicks anywhere on your page to increase the chances of being subscribed successfully.

  4. Close your modal. Our web SDK will separately open the popup to subdomain.onesignal.com where the user will be finally subscribed.


How to trigger Permission Requests

Permission Requests appear directly from the browser asking users to allow notification permissions.

HTTPS Only

Users are directly subscribed after clicking Allow, without any further interaction required.

HTTP Only

Users must click on a post-request modal, which then opens a popup window that actually subscribes them.

The browser permission request can be automatically shown to site visitors, or be triggered programmatically to be shown at a later time.

Automatically triggering Permission Requests

The browser permission request is automatically shown when:

For HTTPS sites:

  • Your OneSignal JavaScript initialization settings contains the autoRegister: true property
  • The user has not clicked the X button to dismiss the request
    • Users who dismiss the prompt will not see it again for 8 hours

Wordpress - In the Configuration tab of our WordPress plugin, you must additionally enable Automatically prompt new site visitors to subscribe to push notification.

For HTTP sites:

Manually triggering Permission Requests

For HTTPS sites:
The browser permission request can be triggered manually via registerForPushNotifications(). You may wish to do this after presenting users a Permission Message, such as the Slidedown Permission Message. Note that Permissions Requests may not always appear.

For HTTP sites:
The simulated browser permission request can be triggered manually via showHttpPermissionRequest() as long as the httpPermissionRequest section of your init settings has enabled it.

How to customize Permission Requests

Permission Requests are shown by the device or browser and are not customizable. All devices and browsers present the request in the appropriate language.

FAQ

Why does my Permission Message keep showing up?

The Slidedown Permission Message is automatically shown when:

  • Your OneSignal JavaScript initialization settings contains the autoRegister: true property. On HTTPS sites, this automatically triggers the browser's native permission prompt. See step 2 of our Web Push SDK Setup (HTTP) guide for a code example of where to place the autoRegister property. On HTTP sites, this automatically shows the slidedown pre-permission message prompt for a similar effect.
  • The user visited your page in a new browser tab or window. Users navigating between links on the same browser tab or refreshing the same page will not trigger the drop-down prompt
  • All of the reasons listed below in "Why isn't my Permission Message showing up?" (next section) must not occur. If any of those reasons are true as well, we do not show the Slidedown Permission Message.

When the first two conditions are true (and none of the conditions listed in the next section are true), the slidedown pre-permission message will slide down from the top as soon as the page loads, covering other page elements. On a mobile browser, the message will slide up from the bottom.

Why isn't my Permission Message showing up?

Slidedown Permission Message

Even if you trigger showHttpPrompt(), it may not always show the message. The message will not be shown if any of the following are true:

  • The user previously dismissed the message by clicking the "No Thanks" button
  • The user has blocked notifications for your-subdomain.onesignal.com
  • The user is already successfully subscribed to notifications
    A user who is already subscribed does not need to re-subscribe.
  • You have manually opted out the user via our setSubscription(false) API

If you've intentionally disabled a user's permissions by calling setSubscription(false), you must manually opt the user back in by calling setSubscription(true); our drop-down prompt will not show.

If the prompt is not shown, the showHttpPrompt() method returns a Promise that resolves to a string value briefly describing the reason the prompt was not shown. You may also enable debug logging for the SDK via OneSignal.log.setLevel('trace'); to see explanations of why the prompt is not shown.

Why isn't my Permission Request showing up?

A Permission Request may not show when triggered if one of the three conditions is true:

  • The user has already allowed notifications
  • The user is already subscribed
  • The user blocked notifications

Customize Permission Messages

Prompting users to opt-in to your notifications for Web Push (Chrome, Firefox, and Safari) notifications.

For Developers