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

Action Buttons

Concepts - Additional actions users may take on notifications

Typically when a user receives a notification, there is only a single action available - tapping on the notification. Action Buttons allow more than one action to be taken on a notification, allowing for greater interactivity within notifications.

Platforms Supported

Platform
Support Notes

iOS

Supports up to 4 buttons with Rich Notifications

Icons not supported

Android, Amazon

Supports up to 3 buttons.

Icons not supported on Android 7+

Chrome

Supports 2 buttons (Chrome 48+)
Chrome 50+: action button icon supported.

Firefox, Safari

Buttons not supported

How to Add Action Buttons

Add Action Buttons from the Dashboard

Go to New Message and select Options. Then input your follow platform-specific instructions:

iOS, Android, Amazon - Fill in with the parameters below, and click Add Another to add more buttons:

Parameter
Notes

id

A unique identifier for your button action.

text

The text the button should display.

icon

Android, Amazon - add icon to button

Chrome - Enable Action Buttons and fill in the parameters below. Click Add Another to add a second button:

Parameter
Notes

Action ID

A unique identifier for your button action. The ID of the clicked button is passed to you so you can identify which button was clicked. (e.g. 'accept-button')

Button Text

The text the button should display. Passed to your app so you can identify which button was clicked. (e.g. 'Accept')

Icon URL

A valid publicly reachable URL to an icon. Keep this small because it's downloaded on every notification display. (e.g. 'http://site.com/icon.png')

Launch URL

The URL to open when the notification is clicked. Pass 'do_not_open' to prevent opening any URL. (e.g. 'do_not_open')

Add Action Buttons from the REST API

iOS, Android, Amazon - See REST API Create Notification: Action Buttons. The button id is added to the additionalData variable in the notification opened callback.

Chrome - Use the web_buttons parameter and pass an array of hashes (up to the two) describing the button with id, text, icon, and url. See description of the parameters above.

Add Action Buttons from the SDK

iOS, Android, Amazon - See the SDK Reference for whichever SDK you are using to build your app. The button id is added to the additionalData variable in the notification opened callback.

Chrome - If OneSignal is active on your webpage, you can send the current webpage visitor a test notification using the following code:

/******************/
/** EXAMPLE CODE **/
/******************/
OneSignal.sendSelfNotification(
  /* Title (defaults if unset) */
  "OneSignal Web Push Notification",
  /* Message (defaults if unset) */
  "Action buttons increase the ways your users can interact with your notification.", 
   /* URL (defaults if unset) */
  'https://example.com/?_osp=do_not_open',
  /* Icon */
  'https://onesignal.com/images/notification_logo.png',
  {
    /* Additional data hash */
    notificationType: 'news-feature'
  }, 
  [{ /* Buttons */
    /* Choose any unique identifier for your button. The ID of the clicked button 			 is passed to you so you can identify which button is clicked */
    id: 'like-button',
    /* The text the button should display. Supports emojis. */
    text: 'Like',
    /* A valid publicly reachable URL to an icon. Keep this small because it's 				 downloaded on each notification display. */
    icon: 'http://i.imgur.com/N8SN8ZS.png',
    /* The URL to open when this action button is clicked. See the sections below 			 for special URLs that prevent opening any window. */
    url: 'https://example.com/?_osp=do_not_open'
  },
  {
    id: 'read-more-button',
    text: 'Read more',
    icon: 'http://i.imgur.com/MIxJp1L.png',
    url: 'https://example.com/?_osp=do_not_open'
  }]
);

Action Button Icons (Optional)

Android, Amazon

Not supported on Android 7+

By default icons will not display on Action Buttons. On Android 7 - 6, you can add icons 32x32dp (24x24dp optical square) in size, this means the following pixel sizes:

mdpi = 24x24 pixels in a 32x32 area
hdpi = 36x36 pixels in a 48x48 area
xhdpi = 48x48 pixels in a 64x64 area
xxhdpi = 72x72 pixels in a 96x96 area

Action Button icons will appear next to the button text, such as the icons next to 'Share' and 'View' in this example:


How to Handle the Action Button Click Event

When an action button is clicked, the OneSignal SDK fires a notification click event aka the Notification Opened Callback:

Inside these click events, you can check for the OSNotificationAction actionID which you set when creating the Action Buttons.

If the actionID is available, you can then perform some action within this event handler like Mobile deep-links and URLs or another custom process.

class ExampleNotificationOpenedHandler implements OneSignal.NotificationOpenedHandler {
  @Override
  public void notificationOpened(OSNotificationOpenResult result) {
    OSNotificationAction.ActionType actionType = result.action.type;
    JSONObject data = result.notification.payload.additionalData;
    String customKey;

    if (data != null) {
      customKey = data.optString("customkey", null);
      if (customKey != null)
        Log.i("OneSignalExample", "customkey set with value: " + customKey);
    }

    if (actionType == OSNotificationAction.ActionType.ActionTaken)
      Log.i("OneSignalExample", "Button pressed with id: " + result.action.actionID);

    // The following can be used to open an Activity of your choice.
    // Replace - getApplicationContext() - with any Android Context.
    // Intent intent = new Intent(getApplicationContext(), YourActivity.class);
    // intent.setFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT | Intent.FLAG_ACTIVITY_NEW_TASK);
    // startActivity(intent);

     // Add the following to your AndroidManifest.xml to prevent the launching of your main Activity
     //   if you are calling startActivity above.
     /* 
        <application ...>
          <meta-data android:name="com.onesignal.NotificationOpened.DEFAULT" android:value="DISABLE" />
        </application>
     */
  }
}
let notificationOpenedBlock: OSHandleNotificationActionBlock = { result in
  if let actionID = result?.action.actionID {
    print("actionID =", actionID)
  }
}
^(OSNotificationOpenedResult *result) {
  if (result.action.actionID) {
      NSLog(@"Action ID: ", result.action.actionID)
  }
}
OneSignal.push(["addListenerForNotificationOpened", function(event) {
  console.log("OneSignal notification clicked:", event);
}]);

Done! You should be able to send notifications with Action Buttons now.


FAQ

Why are my Action Buttons not working?

When you get a notification with action buttons on mobile: you need to pull down on it to see the buttons or swipe left and click View. On web, you will need to click the "Settings" button to see the drop down.

Make sure if you added the action button, you added all required fields such as Action Id and Text

How can I use the action button click event?

Chrome

When an action button is clicked, or when the notification body is clicked:

  • A notification click event is fired according to these specifications
  • If the notification body was clicked, the notification URL is opened. If an action button was clicked, the action button URL is opened.
  • Finally, the notification click webhook is fired Webhooks

You can take advantage of these three events to perform whatever you need. For example, using webhooks, you can perform a custom action (e.g. upvoting a story, analytics) when an action button is clicked.

How can I prevent the action button from opening any URL?

Chrome

You can use the following special URL for both the notification launch URL and action button URL.

  • Any URL containing the magic string _osp=do_not_open will not open any URL

This is supported on Chrome and Firefox, but not supported for the Safari web browser. If you target Safari, please provide a URL so that Safari users have somewhere to go. For example, you could use https://yoursite.com/page?_osp=do_not_open.

How can I use the action button to do some work on my page without opening extra windows?

Chrome

Our goal in this example is to open a new tab to our site (if our site isn't already open) when the action button is clicked, and do some work on the page.

Please first read this section of our API reference to understand when our notification click handler fires. It only ever fires on one tab, and the notification launch URL or action button launch URL must at least be the same origin as your site's in order for the notification click handler to trigger.

We'll first modify our JavaScript initialization options so that the notification click handler is called as long as our notification launch URL or action button launch URL shares our site's origin. For https://site.com, this means our notification click handler will be called as long as our notification launch URL or action button launch URL begins with "https://site.com...".

/* Do NOT call init twice */
OneSignal.push(["init", {
  /* Your other init settings ... */
  notificationClickHandlerMatch: 'origin', /* See API reference: https://documentation.onesignal.com/docs/web-push-sdk#section--notificationopenedcallback- *.
  /* Your other init settings ... */
}]);

Now we'll add a listener to capture the notification click event, that does some pretend work:

OneSignal.push(["addListenerForNotificationOpened", function(event) {
  console.log("OneSignal notification clicked:", event);
  /*
  {
      "id": "96a0dd96-5b63-47e2-9e67-58ca9a315325",
      "heading": "OneSignal Web Push Notification",
      "content": "Action buttons increase the ways your users can interact with your notification.",
      "data": {
          "notificationType": "news-feature"
      },
      "url": "https://example.com",
      "icon": "https://onesignal.com/images/notification_logo.png",
      "buttons": [
          {
              "action": "like-button",
              "title": "Like",
              "icon": "http://i.imgur.com/N8SN8ZS.png",
              "url": "https://example.com"
          },
          {
              "action": "read-more-button",
              "title": "Read more",
              "icon": "http://i.imgur.com/MIxJp1L.png",
              "url": "https://example.com"
          }
      ],
      "action": "like-button"
  }
  */
  
  // We might send a lot of different notifications; the notification we just sent came with additional data that describes the kind of notification that was sent. We sent "notificationType" with our additional data field (notificationType is not built in).
  var isNewsFeatureNotification = event.data && event.data.notificationType === 'news-feature';
  if (isNewsFeatureNotification) {
    // What action button did they click?
    if (event.action === "") {
      // An empty string means the notification body was clicked (no action button was clicked)
      // Keep in mind action buttons are only supported on Chrome 48+ so some users will only be able to click the notification body
    } else if (event.action === 'like-button') {
      // The "Like" action button was clicked
      alert("Glad you liked it! We'll show you similar stories in the future");
    } else if (event.action === 'read-more-button') {
      // The "Read more" action button was clicked
      alert('Showing you the full news article...');
    }
  }
}]);

Now when sending a notification (see above for how to send a notification with action buttons), we can use a notification launch URL and action button launch URLs that begin with our site's origin to trigger our notification click event.

If the site is already open, no new tab will be opened. Otherwise, a new tab will be opened and the new tab will receive the notification click event.

How can I send a Notification with a Launch Action button?

iOS, Android, Amazon

We provide a callback method that you can set in your app code that will receive data about which button was pressed (if any) on the notification that launched the app. With this method, you can run custom code to execute depending on the pressed button. This method can be found in the SDK Reference for the SDK you are using to build your app.


Action Buttons


Concepts - Additional actions users may take on notifications

Suggested Edits are limited on API Reference Pages

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