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.
Action Buttons let you add multiple, labeled actions to a single push notification, so users can respond without opening your app or site first. Depending on the operating system and device, users reveal buttons by expanding the notification (long press, swipe + View, or an expand affordance).

​
Add action buttons

You can configure Action Buttons in Templates, directly when composing a message in the dashboard, or via the API.

​
Dashboard & template setup

When creating a push, open Advanced Options > Action Buttons.

Image showing action buttons to be added for iOS and Android

​
API 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)

​
Handle action button clicks

When a user taps a button, OneSignal delivers the Action ID to your app/site. You can either use the default behavior (open your app/site) or override it.

​
Default behavior (Open App/Site, Then Handle)

  1. The app/site opens (or is focused on web).
  2. Your click/open listener receives the event with the Action ID. (See mobile SDK reference or web SDK reference for click listener details.)

​
Prevent app launch from action button clicks

​
Supported platforms & limits

PlatformButtons SupportedNotes
iOSUp to 4Icons on iOS 15+. Requires categories for background handling.
Android / Amazon / HuaweiUp to 3No button icons from Android 7+.
Web – ChromeUp to 2Buttons and icons supported. _osp=do_not_open supported.
Web – FirefoxNo buttons_osp=do_not_open works for the launch URL only.
Web – SafariNo buttons_osp=do_not_open not supported. Provide a real URL.
Users often need to expand the notification to see buttons (e.g., long press on iOS, swipe + View on some Android OEMs).

​
Troubleshooting

​
Buttons don’t show up

  • Expand the notification (long press, swipe + View, or expand).
  • Verify you added Action ID and Label for each button.
  • Check platform limits (e.g., only 2 buttons on Chrome).

​
Clicking a button doesn’t open the browser on mobile web

If the browser is in the background or fully closed, most mobile browsers (including Chrome) will not come to the foreground or open the URL, even though click events still trigger in the service worker. This is intentional browser behavior to prevent background apps from interrupting the user.
  • Most mobile browsers won’t foreground themselves from a background service worker. Clicks still fire in the worker, but the tab doesn’t open. This is intentional.
  • Ensure the launch URL and the button URL are exactly identical (including trailing slashes) if you expect the tab to be focused instead of opening a new one.

​
Icons don’t appear

  • iOS must be 15+ for button icons.
  • Android 7+ does not render action button icons.
  • On web, confirm the icon URL is publicly accessible and small (fast to download).

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