Image showing action buttons in iOS

This guide applies only to push notifications. For in-app messages, see In-App Messages: How to add Click Actions.
Push notifications typically allow only a single interaction—tapping the message. Action Buttons expand this by enabling multiple user-defined actions directly from the notification, improving user engagement and interactivity. Users can access Action Buttons by expanding the notification (e.g., long press, swipe + View, or expand button), depending on their OS and device.

​
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.

Image showing action buttons to be added for iOS and Android

​
API action button setup

  • Mobile Apps: Use the buttons parameter. Pass an array of up to 3 objects with id, text, and icon.
  • Web (Chrome): Use web_buttons, passing up to 2 objects with id, text, icon, and url.

​
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

  • iOS supports action button icons for iOS 15+
  • Android stopped supporting action button icons for Android N (AKA 7)

​
Handling action button click events

When an action button is clicked, the SDK fires a notification click event with the actionID. Apps can respond in two ways: Default Behavior:
  • App opens and click event is handled by SDK.
  • Use listeners to detect which button was clicked.
Preventing App Launch: You can override default open behavior:
  • Android: Follow this guide to use a NotificationExtenderService.
  • iOS: Include ios_category and register actions using UNNotificationCategory.

​
Handling action buttons without opening the app

Android: within the AndroidManifest.xml follow the Android SDK setup guide to disable the default behavior of always opening the app. This will allow you to override the normal open events and handle the action using custom code and the Mobile Service Extensions. 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?

PlatformSupport Notes
iOS- Supports up to 4 buttons
Android, Amazon- Supports up to 3 buttons
Chrome- Supports 2 buttons
Firefox, Safari- Buttons not 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 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.

​
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.
Need help?Chat with our Support team or email support@onesignal.comPlease include:
  • Details of the issue you’re experiencing and steps to reproduce if available
  • Your OneSignal App ID
  • The External ID or Subscription ID if applicable
  • The URL to the message you tested in the OneSignal Dashboard if applicable
  • Any relevant logs or error messages
We’re happy to help!