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 three Permission Message designs: Fullscreen, Slidedown, 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, 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

Subscription Bell

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

This section shows you how to trigger and customize the Subscription Bell. If you want to learn more about asking for push notification permissions, go here.

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. See this image for instructions

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

The Slidedown Permission Message displays on top of your site, in the top center of the browser. While not as attention-grabbing as the Full Screen Permission Message, users must still dismiss it to fully view your site.

This section shows you how to trigger and customize the Slidedown Permission Message. If you want to learn more about asking for push notification permissions, go here.


Desktop (Firefox/Chrome) and Android Chrome versions of Slidedown Prompt

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.

Not seeing the slidedown prompt? See our FAQ below.

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 the instructions in this image.

Customizing Icon

HTTPS, HTTP, Wordpress - You may customize the website icon shown in the Slidedown Permission Message by editing the Default Notification Icon URL in your dashboard. Go to App Settings by clicking Configure next to the Google Chrome & Mozilla Firefox platform settings.

To edit the website icon, enter a link to an icon file that is at least 80x80 pixels (Recommended size is 192x192). The file must be .png or .jpg.

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


Fullscreen Permission Message

The Fullscreen Permission Message is the most attention-grabbing message design. Users must dismiss it to continue using your site.

This section shows you how to trigger and customize the Fullscreen Permission Message. If you want to learn more about asking for push notification permissions, go here.

HTTPS - The fullscreen permission message is presented on top of your site contents:

HTTP - The fullscreen permission message is presented in a separate pop-up window:

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 cannot 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 custom link or button 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',
        /* ... */
    }
}]);

Customizing Icon

HTTPS, HTTP, Wordpress - You may customize the website icon shown in the Fullscreen Permission Message by editing the Default Notification Icon URL in your dashboard.

To edit the website icon, enter a link to an icon file that is at least 80x80 pixels (Recommended size is 192x192). The file must be .png or .jpg.

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


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>

Permission Requests

HTTPS Only

Permission Requests appear directly from the browser asking users to allow notification permissions. Users are directly subscribed after clicking Allow, without any further interaction required.

Unlike permission messages, if you present users with the browser's permission request and users click Block, your site will never be able to prompt users again to register for push notifications. This is why we recommend customers use one of the above permission messages instead.

The only way to get around a user blocking your site's push notifications forever is to show them how to manually change their browser settings - which users rarely do.

Automatically triggering Permission Requests

Not Recommended - We do not recommend clients automatically trigger permission requests because it creates a poor user experience.

The browser permission request is automatically shown when:

  1. Your OneSignal JavaScript initialization settings contains the autoRegister: true property.

    • See Web Push SDK Setup (HTTPS) for a code example of where to place this property.
    • Note: OneSignal will ignore this for users with Chrome on Android, due to changes in that browser's prompting behavior. Read more
  2. 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
    • Note: Chrome on Android does not show the 'X' button, meaning users cannot dismiss these prompts. Read more

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

Manually triggering Permission Requests

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.

OneSignal does not recommend triggering Permission Requests without users first opting-in via another prompting method. We only recommend manually triggering Permission Requests when you have presented users with an appropriate Permission Message first.

Customizing Permission Requests

Permission Requests are not customizable because they are shown by the device or browser. 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.
    • HTTPS - this automatically triggers the browser's native permission prompt. See step 2 of our Web Push SDK Setup (HTTPS) guide for a code example of where to place the autoRegister property.
    • HTTP - 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