Skip to main content


Apple Specific

Actions is a generic system that allows you to easily integrate the Home Assistant automations system into multiple areas of iOS and Apple Watch.

Creating Actions#

You can create actions either from within the app itself or in your Home Assistant configuration.yaml

Creating Actions in the App#

Actions are created from the Actions section of the App Configuration page within the companion App for iOS. Each action has required fields depending on your device:

  • Name: the name of the action, this will be returned in the Home Assistant event fired by the app.
  • Text: the descriptive text shown on the phone and watch. It is best to keep this relatively short as there is limited space on each action's button.
  • Text Color: the color of the text defined above.
  • Background Color: the color of the button created for the action.
  • Icon: an icon to display to the left of the text on the action's button.
  • Icon Color: the color of the icon on the action's button.

For the three color fields, the color is selected by tapping the color-picker circle in each field.

Creating Actions in Home Assistant#

You can define actions in your Home Assistant configuration.yaml. This requires at least Home Assistant 0.115 and version 2020.6. The following is an example entry.

ios:  actions:    - name: Fred      background_color: "#000000"      label:        text: "Hello, World"        color: "#ff0000"      icon:        icon: earth        color: "#ffffff"

Colors should be in hex format and icons should be from the mdi set.

After saving these changes you will need to restart Home Assistant and then, in the Companion App, go to the Actions section of App Configuration. It should sync automatically, but you can also pull-to-refresh to sync.

Using Actions#

When an action button is pressed a ios.action_fired event is fired on Home Assistant's event bus. The event data consists of a JSON-formatted dictionary of attributes relating to the action.

contextChild dictionary relating the user that triggered the event and the ID of the event
dataChild dictionary containing key information about the action and its origin
event_typeAlways ios.action_fired
originAlways REMOTE
time_firedData and time the action was fired, formatted as an ISO timestamp , e.g. midnight on Christmas day in Lapland (Eastern European Time, UTC+2), would be 2019-12-25T00:00.000000+02:00.

The attributes contained within data are:

actionIDA unique identifier for the action.
actionNameThe name of the action as given in the Name field when creating the action in iOS or action field when using Android.
sourceDeviceIDThe device ID set in the App Configuration page of the companion app.
sourceDeviceNameThe name of the device from which the action was triggered. This is the Device Name set in iOS under Settings App>General>About or for Android it is set in Settings > About Phone.
sourceDevicePermanentIDA unique identifier of the device through which the action was triggered
triggerSourceWhat part of iOS the action with fired from. Either: widget for the Today screen, appShortcut for quick actions accessed through 3D touch or watch if fired from an Apple Watch.

The attributes contained within context are:

idA unique one-time ID for the event.
parent_idAlways null.
user_idThe Home Assistant user ID used to authorise the companion app with Home Assistant.

Actions can be used to trigger automations within Home Assistant. An example configuration.yaml entry might be:


automation:  - alias: "Action Turn Lights Off"    initial_state: true    trigger:      - platform: event        event_type: ios.action_fired        event_data:          actionName: 'Bed Time'    action:      - service: light.turn_off        entity_id: group.all_lights

Note that attributes located in the data and context are accessed through event_data and event_context respectively within the automation.

You can use the Events page within Home Assistant's developer tools to show all information contained with the event for a particular event by subscribing to ios.action_fired and triggering the action from you device.

Apple Watch#

The Apple Watch App provides access to actions you have created. Once you have created an action within the Actions page, open the Home Assistant watch and the action list should sync. Actions triggered on Apple Watch carry a slightly different payload.

Home Screen Quick Actions#

Home Screen Quick Actions provides a convenient shortcut to your actions and is accessed by 3D Touching the Home Assistant companion app icon on your home screen.

Today View Widget#

The Today View Widget is another route through which actions can be fired. To add the Home Assistant widget to your Today View:

  1. Swipe right while on the Home screen or Lock screen.
  2. Scroll to the very bottom and tap the Edit button.
  3. Find the "Home Assistant - Actions" widget in the "More Widgets" list and then tap the green + button to add it.
  4. Rearrange as you'd like and then tap Done.