Action Buttons

Additional actions users may take on notifications

Typically when receiving 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.

Quick ReferenceDetails
Adding Action Buttons To PushAction Buttons can be added to Push in the following ways:
- Using the OneSignal Dashboard
- Using the OneSignal API
- Using the OneSignal SDK
Handling the Action Button Click EventOneSignal's default behavior will open the App to handle the Action Buttons through the SDK Click Event.

You can prevent Action buttons from opening the App or Site and handle by following these links:
- Apps: Handling Action Buttons without Opening the App
- Web: Adding a query string to the url.

Supported Platforms

PlatformSupport 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 Mobile App Action Buttons from the Dashboard

In Sending Push Messages under Advanced Options. Input your follow platform-specific instructions. Fill in with the parameters below, and click Add Another to add more buttons:

2500

🚧

Action ID Required

You must add an Action Id and Text for this button to work. The Action ID should be different if you add multiple buttons.

DashboardAPI ParameterNotes
Action IDidA unique identifier for your button action.
TexttextThe text the button should display.
IconiconAndroid, Amazon - add icon to button

Chrome - Under Platform Settings > Send to Google Chrome Enable Action Buttons and fill in the parameters below. Click Add Another to add a second button:

2500
ParameterNotes
Action IDA 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 TextThe text the button should display. Passed to your app so you can identify which button was clicked. (e.g. 'Accept')
Icon URLA 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 URLThe 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

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

curl --include \
     --request POST \
     --header "Content-Type: application/json; charset=utf-8" \
     --header "Authorization: Basic YOUR_REST_API_KEY" \
     --data-binary "{\"app_id\": \"YOUR_APP_ID\",
\"contents\": {\"en\": \"English Message\"},
\"included_segments\": [\"Subscribed Users\"],
\"buttons\": [{\"id\": \"id1\", \"text\": \"button1\", \"icon\": \"ic_menu_share\"}, {\"id\": \"id2\", \"text\": \"button2\", \"icon\": \"ic_menu_send\"}]}" \
     https://onesignal.com/api/v1/notifications

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.

curl --include \
     --request POST \
     --header "Content-Type: application/json; charset=utf-8" \
     --header "Authorization: Basic YOUR_REST_API_KEY" \
     --data-binary "{\"app_id\": \"YOUR_APP_ID\",
\"contents\": {\"en\": \"English Message\"},
\"included_segments\": [\"Subscribed Users\"],
\"web_buttons\": [{\"id\": \"id1\", \"text\": \"button1\", \"icon\": \"ic_menu_share\",\"url\": \"https://yoursite.com\"}, {\"id\": \"id2\", \"text\": \"button2\", \"icon\": \"ic_menu_send\",\"url\": \"https://yoursite.com\"}]}" \
     https://onesignal.com/api/v1/notifications

Add Action Buttons from the SDK

Mobile - 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:

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)

Not supported on Android 7+ according to the Android team's blog post on Android N (AKA 7) it is not longer supported.

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:

373

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 Handler. If you want to handle the notification outside of our SDK or without opening the app see below: Handing Action Buttons without Opening the App

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);
}]);

Handing Action Buttons without Opening the App

Android: within the AndroidManifest.xml follow this guide to disable the default behavior of always opening the app. This will allow you to override the normal open events.

iOS: you can add an ios_category within the notification. This will allow you to add custom actions through the UNNotificationCategory Object. See Apple's Declaring Your Actionable Notification Types for more details.


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?

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?

Web Push Only

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?

Web Push Only

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.

Why is there a close action button?

By default web push notifications on Windows 10 include the Close button.

However, if you add your own action button, then this close button is removed. So, in either case the notification will remain on-screen till the user interacts with it. 

This is designed by Google to give the users the chance to interact with the notification.