Action buttons described in this guide are for push notifications only. For custom buttons on In-App Messages, see In-App Messages: How to add Click Actions.

Typically when receiving a push notification, there is only a single action available - tapping on the notification. However, Action Buttons provide more than one action to be taken on a notification, allowing for greater interactivity.

Action buttons can be accessed on the notification when viewing the full, expanded notification. Depending on the device and operating system version, this can happen by either long pressing it, sliding it and clicking the "View" button, and/or expanding it with a button.

How to Add Action Buttons

Action buttons can be set within push notifications using Templates or directly from the dashboard or API.

Dashboard Action Button Setup

When Sending Push Messages, Action Button fields are under Advanced Options.

API Action Button Setup

See REST API Create Notification: Action Buttons.

Mobile - Use the buttons parameter and pass an array of objects (up to the three) describing the button with id, text, and icon.

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.

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

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

Action Button Properties

• Action ID: A unique identifier for the specific button action. The ID of the clicked button is passed to you so you can identify which button was clicked. (e.g. 'accept-button')
  • Must be unique per button.
  • Available in the OSNotification Payload and can be accessed within the SDK Notification Opened Event Handler.
  • API: id property
• Label: The text the button should display to your users. (e.g. 'Accept')
  • API: text property
• Icon: Optional icon displayed with the button label. Not available on all platforms and operating systems. See FAQ below for details.
  • Mobile apps must include the button within its image resources. See Action Button Icons below for details.
  • Websites can use 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)
  • API: icon property
• Button URL: The URL to open when the notification is clicked. Pass 'do_not_open' to prevent opening any URL. (e.g. 'do_not_open')
  • Web only
  • API: url property

Action Button Icons

Optional

Not supported on Android 7+ according to the Android team's blog post on Android N (AKA 7) it is no 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

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.

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

What Platforms are Supported?

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.

How can I customize the appearance of my mobile app action buttons?

This will require writing native Java code and manipulating the push notification layout using the Notification Service Extension.

To change the action button text color, add something like this within the NSE:

// Example from Stackoverflow https://stackoverflow.com/questions/41073294/how-to-change-notification-action-text-color-in-android-n/56873390#56873390
Notification notification = new NotificationCompat.Builder(context, channelId)
        ...
        .addAction(new NotificationCompat.Action.Builder(
                            R.drawable.ic_fire,
                            HtmlCompat.fromHtml("<font color=\"" + ContextCompat.getColor(context, R.color.custom_color) + "\">" + context.getString(R.string.fire) + "</font>", HtmlCompat.FROM_HTML_MODE_LEGACY),
                            actionPendingIntent))
                    .build())
        .build();

If possible you will want to modify the action button instead of using addAction. Otherwise, you won't be able to define the button text from OneSignal or track the click.

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.

How to track action button clicks?

It is required to add a custom code to check it. When you handle the action button click event, you can use the notification opened event to get the actionID and send that actionID event to the analytics.