Apple Shortcuts Home Assistant iOS Tutorial
This walkthrough should help you integrate Home Assistant and Shortcuts which opens the door to super powerful automations. I plan to write a condensed version of this walkthrough for the official Home Assistant Companion documentation, but this is just a quick temporary guide to help people for now.
Before starting, install the iOS 13 Beta. It's free, open to the public, and easy to do. Visit the Apple Beta Software Program from either an iPhone or iPad, sign in with your Apple ID, and enroll your device. This installs a very small "beta profile" on your device which allows you to get beta versions from the normal Software Update screen.
First you'll want to set up an automation that can receive webhooks. Here's the one I've made that you can simply copy and paste into your setup.
automation:
- alias: 'Shortcuts Webhook Call Service'
initial_state: 'on'
trigger:
platform: webhook
webhook_id: shortcuts_call_service
action:
service_template: '{{ trigger.json.service }}'
data_template:
entity_id: '{{ trigger.json.entity_id }}'
If you don't have Home Assistant Cloud, your webhook URL would be something like this:
https://your-ha-instance.url:8123/api/webhook/shortcuts_call_service
If you're a Home Assistant Cloud subscriber see directions for configuring webhooks on the Nabu Casa site. Basically though you head to the Home Assistant Cloud page and copy the link from the "Webhooks" section at the bottom, super easy. Your cloud webhook URL will start with https://hooks.nabu.casa/
Now that you have the webhook URL, time to make the shortcut.
THE EASY WAY - If you're new to Shortcuts or would rather do things the easiest and quickest way possible, you can simply install the shortcut I've created. ⭐ CLICK HERE TO GET THE SHORTCUT ⭐ iOS 13 users will first have to go to iOS Settings -> Shortcuts and toggle "Allow Untrusted Shortcuts" on (see screenshot). Once installed there are comments inside the shortcut explaining where to place the webhook URL and how to edit it.
THE MANUAL WAY - Here are the manual instructions if you wish to create it from scratch. Even though this way takes a few minutes longer, I recommend going through this process since it'll give you a better understanding of Shortcuts.
- Open Shortcuts app, and make sure you're on the first tab (My Shortcuts).
- Press the "Create Shortcut" button at the very bottom (or the blue + button in top right corner). Now you'll see a screen that says "New Shortcut" with a button that says "Add Action" - press this button to begin.
- At the top of the screen is a search bar that says "Search for apps and actions." Type in the word "Text" and it will start filtering and you'll see the word "Text". Simply tap that to add it to your Shortcut as the first action/step. This text field is where you'll paste in the webhook URL from the above step.
- Now press the big blue + button to add your second action. Following the same process listed in the step above, search for "Copy to Clipboard" and tap it to add.
- Now press the big blue + button again to add your third action, again following the same procedure. This time search for "URL" and add the "URL" action. Once this is added, tap the URL (by default it shows
apple.com). Rather than typing in a new URL, you're going to look right above the keyboard, scroll this to the right a bit and select "Clipboard" option. - Now press the big blue + button again to add your fourth and final action. Search for "Get contents of URL" and tap to add it. Once that's added, look for the "Show More" button on that action. By default the Method will be "GET" but you need to change it to "POST."
- Add the headers for
serviceandentity_id(expand on this later, gotta run)
Now you're done. Name your Shortcut whatever you want and save.
The other method is creating shortcuts directly in the iOS app. If you're unfamiliar with Shortcuts app and are more comfortable with Home Assistant, this might be an easier option for you.
- In the iOS beta app, tap "App Configuration" in the sidebar and then select "Siri Shortcuts."
- This page sort of resembles the Home Assistant "Services" page and gives you access to literally every service on your Home Assistant instance. You can run scripts, trigger automations, toggle input_booleans, whatever you can think of. For this example we're going to run an existing automation, so we'll pick the
automation.triggerservice. - On this screen you'll see a field for "Shortcut name" which. Tap on the
entity_idto select your automation to run. - Once you've selected the automation
entity_idfrom the list, press the "Add to Siri" button which will take you to a screen. This is going to be the name of your Shortcut and also how you can trigger it from Siri.
Now that you've created this Shortcut you can launch it in a number of ways - by voice using Siri or by tapping on it inside the Shortcuts app or Today Widget, or by optionally adding it to your Home Screen.
The real power is when you add this to other shortcuts via the "Run Shortcut" command (expand on this later).
After you've created some Shortcuts, you can also launch them from within Home Assistant. Here's an example of how you'd launch a Shortcut using a standard weblink inside a Lovelace Entities card. Simply update the part after ?name= with the name of your shortcut.
- type: weblink
name: Run Shortcut
url: "shortcuts://run-shortcut?name=Your Shortcut"
icon: mdi:rocket
If you'd rather have a button instead, you can do this with the custom Button Card.
- type: "custom:button-card"
name: Shortcut Launcher
color_type: card
icon: mdi:rocket
tap_action:
action: url
url: "shortcuts://run-shortcut?name=Your Shortcut"
Note that these Shortcuts URL's will only work while on your iOS device. Clicking on these links from a desktop computer will do nothing.
Easily the best new feature of Shortcuts in iOS 13 is the introduction of Personal Automations. Since Shortcuts was acquired by Apple and is now a default app bundled with iOS, it now has access to system-related functions.
You can run automations based on time of day, location, when connecting or disconnecting to CarPlay, connecting to Wi-Fi networks, connecting to a specific Bluetooth device, starting or stopping an Apple Watch workout, stopping or snoozing an Alarm, opening specific apps, scanning NFC tags, and enabling things like Airplane Mode, Low Power Mode, or Do Not Disturb.
For this example we're going to run an existing Home Assistant "Morning Routine" automation after we stop our morning wakeup alarm.
Here's how to create a personal automation:
- In the Shortcuts app go to the second tab titled "Automation" and press the blue + button in the top right, then select "Create Personal Automation" on that screen.
- This is the page where you select your trigger. In this example we're going to pick the "Alarm" option.
- You'll have a couple of self-explanatory options on this page: you can run this automation for any alarm (which you probably don't want), specific existing alarm(s), or just your wake-up alarm. You also choose whether you want this to run when the alarm is snoozed or stopped completely. For this example you'll probably want to pick when your wake-up alarm is stopped. Hit the "Next" button in the top right after making your selection.
- Now you're taken to a screen where you define actions. Assuming that you've followed the above guides and created a Shortcut already, you can simply press "Add Action," search for the "Run Shortcut" action, and select your "Morning Routine" shortcut. If not follow the guides above for examples on how to create a Shortcut.
- You're on the final screen now. This is more of an overview page, but it has one very important setting at the bottom. You're going to want to turn off the "Ask Before Running" toggle which will allow the shortcut to execute by itself (otherwise you'd have to tap on a notification to run it).
Now when you stop your morning wake-up alarm on your iPhone, it will automatically run your Home Assistant morning routine automation. Pretty cool, right?
Also new in Shortcuts for iOS 13 is NFC support. NFC stickers are affordable and tiny stickers that are typically the size of a US quarter. You hold your iPhone next to these stickers (much like how you would use Apple Pay) and it will run a Shortcut that you defined.
Buying NFC stickers
NFC stickers are very cheap, typically no more than a dollar or two per sticker for the very best ones. If you don't mind waiting, you can get a pack of ten for $1 from AliExpress. Here's the Amazon link for the stickers I use. This is a good time to mention that not all NFC stickers are created equally. For example, some work on metal surfaces and others do not (the ones I use do not work on metal surfaces). Think about how and where you plan to use these stickers and adjust your purchasing decision accordingly.
Creating NFC automations
This is done by creating a Shortcuts "Personal Automation" as described in the section above. Pick NFC, scan an NFC sticker and give it a name, then select what Shortcut you want to run.
Flesh this out later...