Adding Actions to Notifications on watchOS

Use actionable notifications to provide a set of responses for the notification.


An actionable notification is a notification with associated actions, letting the user respond directly from the notification’s long-look interface.

To create an actionable notification:

  • Define a notification category

  • Associate actions with the category

  • Assign the category to a notification

On Apple Watch, the long-look interface displays the actions as buttons below the notification’s content. Your watchOS app can also provide suggested responses for text input actions, and can respond to actions from notifications received on the watch.

Create a Notification Category

Before you can add actions to a notification, you must create a notification category and register the actions for that category. When you register actions, you specify the title for the action button and the action’s identifier. By default, the system launches your app in the background to handle the action. If you want your app to handle actions in the foreground, you must specify the UNNotificationActionOptionForeground option when creating the action. For detailed instructions, see Declaring Your Actionable Notification Types.

The following rules determine where you create the notification category and actions:

  • For all remote notifications, create the category and actions in your iOS app.

  • For local notifications scheduled on iPhone, create the category and actions in your iOS app.

  • For local notifications scheduled on Apple Watch, create the category and actions in your watchOS app.

Set the Notification’s Category

To add the actions to a notification, specify the notification’s category in its content. For local notifications, specify the category name using the categoryIdentifier property of your UNMutableNotificationContent object. For remote notifications, set the category name as the value of the category key in the notification’s payload.

When delivered, the system uses the category name to look up the associated actions. It creates buttons for each action and attaches those buttons to the notification interface.

Offer Text Input Suggestions

Most actions simply create a button that the user can select, but text input actions let the user type in a response. When the user selects a text input action, the system displays a control that lets the user enter or dictate text. The system then includes this text in the response object that it delivers to your app. For more information, see UNTextInputNotificationAction.

On watchOS, you can provide suggested responses, making it easier for users to respond. To provide suggested responses, override the notification interface controller’s suggestionsForResponseToActionWithIdentifier:forNotification:inputLanguage: method and return an array of strings. When the user selects the associated action, watchOS presents these strings as suggestions.

Respond to Actions

When the user taps an action button, the system launches your app and calls your notification delegate’s userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler: method. The response parameter’s actionIdentifier property contains the identifier for the selected action. Implement your delegate’s userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler: method to check this identifier, and then perform the corresponding task. For more information, see Handling Notifications and Notification-Related Actions.

The following rules define where the action is handled:

  • The system always handles foreground actions on the device where the user selected the action. For example, if the user selects a foreground action on Apple Watch, the system launches your Watch app and delivers the user’s response to the app.

  • The watchOS app handles background actions for local notifications scheduled on Apple Watch.

  • The iOS app handles background actions for local notifications scheduled on iPhone, regardless of where the notification appeared.

  • The iOS app always handles background actions for remote notifications, regardless of where the notification appeared.

If you want to handle the action in your watchOS app, you must either use foreground actions, or schedule the actionable notificaiton as a local notification on Apple Watch. The iOS app handles all the other actions.

See Also

Custom Interfaces and Actions

Customizing Your Long-Look Interface

Create custom interfaces for your watchOS app’s notifications.

Adding Interactive Controls to a Long-Look Interface

Define a dynamic notification controller that responds to user interactions on watchOS.