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

Bell Prompt

OneSignal Subscription Bell Prompt Details: Customization, Triggering, and FAQ

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


Customizing the Bell Prompt

You can customize the OneSignal Bell Prompt's color, size, bottom position, text and more! Currently you cannot customize the icon or place the bell in the top corners.

Typical Setup Bell Customizations

All customizations happen within the Settings > All Browsers Configuration > Step 3 Permission Prompt Setup. Select the Subscription Bell.

There are many ways to customize the bell. Our recommendation would be to use the default settings, but change the Color to fit your site's unique color scheme.

When finished, press Save and Save again on the next page to see this go into effect.

WordPress Slide Customizations

The OneSignal WordPress Plugin handles all available visual customizations through the plugin.

Under Prompt Settings & Subscription Bell turn on Enable the Subscription Bell to start toggling the customizations.

Custom Code Setup Bell Customizations

The Custom Code Setup is for integrating OneSignal with your own custom Javascript. It is recommended to use the Typical Setup.

Use the notifyButton parameter in your web SDK initialization options. You may toggle between different examples for Bell Prompt customizations.

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.

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 */
    },
    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:"
    }
}
// Your other init options here
notifyButton: {
  enable: true, // Required to use the Subscription Bell
  // Your other Subscription Bell 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'
  },
}
// Your other init options here
notifyButton: {
    /* Your other Subscription Bell 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 Subscription Bell */
                return !isPushEnabled;
            });
    },
}
<link rel="manifest" href="/manifest.json" />
<script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async=""></script>
<script>
  var OneSignal = window.OneSignal || [];
  OneSignal.push(function() {
    OneSignal.init({
      appId: "YOUR_APP_ID",
      notifyButton: {
        enable: true, /* Required to use the Subscription Bell */
      /* SUBSCRIPTION BELL CUSTOMIZATIONS START HERE */
        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:"
        },
        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'
         },
        /* HIDE SUBSCRIPTION BELL WHEN USER SUBSCRIBED */
        displayPredicate: function() {
            return OneSignal.isPushNotificationsEnabled()
                .then(function(isPushEnabled) {
                    return !isPushEnabled;
                });
        }
      }
    });
  });
</script>
<script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async=""></script>
<script>
  var OneSignal = window.OneSignal || [];
  OneSignal.push(function() {
    OneSignal.init({
      appId: "YOUR_APP_ID",
      subdomainName: "your_label", /* The label for your site that you added in Site Setup mylabel.os.tc */
      notifyButton: {
        enable: true, /* Required to use the Subscription Bell */
      /* SUBSCRIPTION BELL CUSTOMIZATIONS START HERE */
        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:"
        },
        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'
         },
        /* HIDE SUBSCRIPTION BELL WHEN USER SUBSCRIBED */
        displayPredicate: function() {
            return OneSignal.isPushNotificationsEnabled()
                .then(function(isPushEnabled) {
                    return !isPushEnabled;
                });
        }
      }
    });
  });
</script>

Triggering the Bell Prompt

Enabled through the Typical Setup Configuration or WordPress Plugin.

For Custom Code Setup.
Show: notifyButton: { enable: true }
Don't Show: notifyButton: { enable: false }

📘

Best Practice!

We recommend showing the bell prompt or Custom Link prompt on at least one page to allow users the ability to subscribe or unsubscribe anytime.


Bell Prompt FAQ

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.

How many times does the prompt show?

If a user clicks "No" on the slide prompt, it waits 3 days before showing again. If they click "No" again, it takes 7 days to show again. If they click "No" a 3rd time, it will show again every 30 days.

Why is the Native Prompt not showing up?

A browser's 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

Updated 3 months ago


Bell Prompt


OneSignal Subscription Bell Prompt Details: Customization, Triggering, and FAQ

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.