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 Reference | Details |
---|---|
Adding Action Buttons To Push | Action 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 Event | OneSignal'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
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 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:

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.
Dashboard | API Parameter | Notes |
---|---|---|
Action ID | id | A unique identifier for your button action. |
Text | text | The text the button should display. |
Icon | icon | Android, 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:

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

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.
Updated almost 2 years ago