Home Assistant iOS Notification (Example With Action Button)

In my previous tutorial we learnt how to setup a basic push notification in Home Assistant with the companion mobile app.

In this tutorial we will learn how to send a push notification to iOS and include an action button that can trigger an automation in Home Assistant. Awesome!

Table of Contents

1. What is an actionable notification?
2. Prerequisite
3. Configure Home Assistant
4. Actionable notification structure
   1. iOS integration
   2. Script
   3. Automation
5. Add the iOS integration
6. Notification script
7. Notification automation
8. Import push configuration
9. Adding the entity button
10. Conclusion

What is an actionable notification?

An actionable notification is the same as a normal notification, only it has the added functionality of a button that can be pressed to fire an automation in Home Assistant.

There are many circumstances where this might be useful. You could generate a notification for when the doorbell is pressed and the action button could fire an automation that unlocks the door.

You could also generate a notification triggered by a motion sensor and the action button gives you the option to activate the burglar alarm.

Perhaps your partner likes to stay in bed during the weekend. Your bed occupancy sensor could give you a notification for when they finally get out of bed. Then simply press your action button to boil the kettle for them, how nice!

Prerequisite

I would recommend that you read my previous tutorial on basic notifications first.

You should have Home Assistant installed and running. A basic understanding of YAML would also be highly beneficial.

If you are not yet familiar with automation or YAML then I would recommend reading the tutorials about automation and scripts first.

You will also need the Home Assistant app installed on at least one device. The Home Assistant Companion App can be downloaded from the iOS App Store or Play Store.

You will also either need the file editor add-on or be familiar with editing the files using your favorite text editor. If you are not familiar with either you may want to check out my tutorial on automationor scripts first.

Configure Home Assistant

You need to be running Home Assistant version 0.95 or newer, I would recommend just updating to the latest version.

First we need to make sure that the default_config integration is added to our configuration.yaml file. If not then you can go ahead and add it.

default_config:

If there is some reason that you have removed it, you can instead enter the following.

mobile_app:
discovery:

So long as you have either of these options within your configuration.yaml file, the companion app will automatically configure itself. 

It is important that you enable notifications during the installation. If you have already installed the companion app and did not enable notifications during the installation, you may need to follow the steps in the troubleshooting section.

Actionable notification structure

In order to create a notification with an action button, we will add YAML code to three different integrations.

iOS integration

In order to use actionable push notifications, they must be configured using the iOS integration. Here we define a set of categories and actions associated with the notifications.

An action is the event that will occur when the actionable notification button is pressed. You can add up to four actions per category and each action will be represented by a button.

A category is simply a group of relevant actions that can be assigned to a notification. For example we could create a category called “lights” with three actions, “main” “LEDs” and “lamps.”

If we assign the category “lights” to a particular notification, the action buttons for “main,” “LEDs” and “lamps” will be available under that notification.

Script

You can send an actionable push notification from anywhere that supports the notify service.

For the example in this tutorial we will add a simple entity button that fires a script, which will send the notification to our mobile device.

Automation

When the actionable notification button is pressed on the mobile device, it will fire an instance of automation within Home Assistant.

In this example we will create a simple automation that turns on a lamp when the button is pressed.

Add the iOS integration

First we need to add the iOS integration to our configuration.yaml file.

ios:
  push:
    categories:

Then we need to add the category and specify the identifier, which should be kept in lower case with no spaces.

ios:
  push:
    categories:
      - name: ioslights
        identifier: 'ios_lights'

Categories are entered in a YAML list under push. To add more categories, use the “-” operator and maintain the correct tabs/spacing.

Next we will add the actions. The texted entered for the title attribute will be the text that appears on the button.

You can choose whether or not to open the Home Assistant app by setting the activationMode to foreground or background.

You can set the action to require the phone to be unlocked first by setting authenticationRequired to true. Leaving it set to false will allow the action to be triggered without unlocking.

The button text will appear red if destructive is set to true. Useful if the action is critical, such as unlocking the front door or triggering the alarm.

ios:
  push:
    categories:
      - name: ioslights
        identifier: 'ios_lights'
        actions:
          - identifier: 'TREE_LAMP'
            title: 'Turn on Tree Lamp'
            activationMode: 'background'
            authenticationRequired: false
            destructive: false

Notification script

Now that we have configured our ios integration we can create an instance under the script integration to send the push notification.

We will create a new script called push_with_action_button and give it an alias and description.

script:
   push_with_action_button:
        alias: Test push with button
        description: 'Send a test push notification with action'
        sequence:

In the sequence we need to specify the service as notify.mobile_app_<your device ID>, where <your device ID> is the name of your mobile device in Home Assistant.

script:
   push_with_action_button:
        alias: Test push with button
        description: 'Send a test push notification with action'
        sequence:      
           service: notify.mobile_app_iphone
           data:

Next we should add the standard messages required for the notification. This is the same as with a standard push notification.

script:
   push_with_action_button:
        alias: Test push with button
        description: 'Send a test push notification with action'
        sequence:      
           service: notify.mobile_app_iphone
           data:
              title: "siytek.com"
              message: "Someone pushed my button!"

Finally we need to specify a category for the notification. We will use the identifier specified under the ios integration for the category that we wish to assign.

script:
   push_with_action_button:
        alias: Test push with button
        description: 'Send a test push notification with action'
        sequence:      
           service: notify.mobile_app_iphone
           data:
              title: "siytek.com"
              message: "Someone pushed my button!"
              data:
                 push:
                     category: "ios_lights"

Notification automation

Finally we can write an automation for each action button. In this example we only have a single action TREE_LAMP as specified earlier by the action identifier under the ios integration.

We will specify the automation under the automation integration. If you already have automation code in place, simply add it beneath the existing code.

automation:
  - alias: Notification turn on treelamp

Next we will specify the trigger and choose event for the platform. We will use ios.notification_action_fired for the event_type to tell Home Assistant to fire this automation when an action button is pressed on our mobile device.

automation:
  - alias: Notification turn on treelamp
    trigger:
      platform: event
      event_type: ios.notification_action_fired

We also need to specify the actionName as “TREE_LAMP” from our earlier action identifier. This will tell Home Assistant to fire this automation when that specific button is pressed.

automation:
  - alias: Notification turn on treelamp
    trigger:
      platform: event
      event_type: ios.notification_action_fired
      event_data:
        actionName: TREE_LAMP

Finally we can specify the action. For this example we will use a simple light.turn_on service to turn on the entity light.treelamp.

automation:
  - alias: Notification turn on treelamp
    trigger:
      platform: event
      event_type: ios.notification_action_fired
      event_data:
        actionName: TREE_LAMP
    action:
        - service: light.turn_on
          entity_id: light.treelamp

Import push configuration

Once you have finished writing the YAML you will need to restart Home Assistant.

We also need to import the push configuration in the Home Assistant app. This needs to be done any time changes are made.

Scroll down to the bottom of the sidebar within the app and tap app configuration.

Then tap notifications to enter the notifications menu. From there just tap import push configuration from server.

Adding the entity button

In order to test our new notification we will add an entity button to the user interface.

We will create the button using the UI editor. From the overview page, click on the three dots and then configure UI in the top right-hand corner of the page.

This will switch on the UI editor mode.

Once on the desired tab, click the orange circle with the plus towards the bottom left of the screen and then choose the entity button card.

In the entity box at the top, enter the entity_id for the script. If you type “script” into the box, a dropdown will appear and you can just find it in the list.

Then simply click save and the button will be added to your user interface. Go ahead and click the button and check out your new actionable notification!

Don’t forget to swipe left and click view in order to see the button if you are on the lock screen.

For notifications appearing at the top of the screen, swipe the notification downwards to access the action buttons.

Conclusion

In this tutorial we have learnt that it is possible to harness the power of actionable notifications in iOS.

This is another great integration within Home Assistant and you should now have the knowledge to go ahead and create your own customised actionable notifications!

Why not give my easy DIY thermostat a try next, as you could also include some fancy notifications!

Thanks for taking the time to read the tutorial and for visiting my site! Be sure to check out some of my other awesome Home Assistant tutorials!