Chapter 7

Notifications

Install the Home Assistant Companion App, connect your phone, and send your first test notification. By the end of this chapter, you will have completed the last mile between Home Assistant noticing something and telling you about it.

Why notifications matter

  • The washing machine finishes → your phone chimes.
  • A door is left open → you get a reminder once you are 100 metres from home.
  • Power returns after an outage → you find out even while you are at work.
  • A camera detects a person → the notification includes a thumbnail.

The Companion App delivers these notifications and is also the most convenient way to use Home Assistant day to day.

In this chapter, you will trigger a notification manually as a test. Chapter 8 shows you how to add notifications to automations—for example, “Send a notification when the washing machine stops” or “Turn on the lights and send a notification when someone arrives home.”

Install the Companion App

  1. Search for “Home Assistant” in your phone’s app store

    iOS: Search the App Store for Home Assistant (the developer is Home Assistant).
    Android: Search Google Play for Home Assistant Companion.

  2. Open the app and select “Log in to Home Assistant”

    The app will scan your local network for a Home Assistant server. Select the server if it appears; otherwise, enter http://homeassistant.local:8123 or your own Home Assistant URL.

What else do you get after installing the app? In addition to push notifications, the Companion App automatically sends data such as your phone’s battery level, location, Wi-Fi network name, and Bluetooth sensor readings to Home Assistant. These appear as entities such as sensor.yourname_battery_level and device_tracker.yourname_phone. You can later use them to turn on the lights when you arrive home or send a reminder when the battery falls below 20%.

Sign in with the account you just created

  1. Enter your username and password

    Use the personal account you created in Chapter 5, not a shared administrator account. This allows notifications to be directed to your phone.

  2. Allow the app to access the required features

    The app will request access to notifications, location, Bluetooth, camera, and other features. We recommend enabling at least:

    • Notifications — Essential for this chapter; make sure they are enabled.
    • Location (Always) — The key to automations that detect when you arrive home or leave.
    iOS note: The “Always” location option must be enabled in iOS Settings. During your first sign-in, you may only be able to select “While Using the App”; afterwards, return to Settings and change the permission to “Always.”

  3. Home Assistant automatically adds your phone and its sensors

    In the Home Assistant web interface, go to Settings → Devices & services. A new device named after your phone—for example, “Alex’s iPhone”—will appear with dozens of sensors for battery level, charging state, Wi-Fi network name, Focus mode, and more.

    Mobile sensors automatically registered by the Companion App
    Figure 7-1 Home Assistant automatically adds the phone’s sensors after the mobile app registers.

Send your first notification

This feature has changed names: The sidebar previously had a separate “Developer Tools” section. Starting with 2026.2, all of it moved under Settings; in 2026.8, “Developer Tools” was shortened to Tools. The current path is Settings → Tools → Actions. On older releases, use Developer Tools → Actions; the tab’s contents are the same. Home Assistant also renamed “Service” to Action in 2024.8. The legacy service: key has accordingly been replaced by action: in current YAML.

  1. Go to Settings → Tools → Actions

    In the Home Assistant web interface, select Settings in the sidebar, select Tools, and then open the Actions tab.

  2. Select notify.mobile_app_XXX in the action field

    XXX is the name of the phone you just connected. The Companion App creates this action automatically.

    The action interface under Settings, Tools, and Actions
    Figure 7-2 The action interface under Settings → Tools. This screenshot shows the former Developer Tools interface.

    Notification action naming convention: notify.mobile_app_<device name>. Non-alphanumeric characters in the device name become underscores. For example, iPhone 13 Pro Max becomes notify.mobile_app_iphone_13_pro_max. To find your phone, search for notify.mobile_app in the action list under Settings → Tools → Actions.

  3. Enter a message and title

    Try this simple test:

    action: notify.mobile_app_xxx
data:
  title: "Test notification"
  message: "First message from HA"

  4. Select “Perform action”

    Your phone should chime immediately. Congratulations—your smart home now has a voice.

Check your result: “Test notification” should appear on your phone within 5 seconds. If it does not, check that (1) the app has notification permission, (2) the phone is not in Do Not Disturb or a restrictive Focus mode, and (3) the Home Assistant server has working outbound internet access.

Advanced: Add action buttons to a notification

A notification can include buttons for you to select instead of displaying static text only:

action: notify.mobile_app_xxx
data:
  title: "Someone rang the doorbell"
  message: "Tap an action below to choose whether to open the door."
  data:
    actions:
      - action: "OPEN_DOOR"
        title: "Open door"
      - action: "IGNORE"
        title: "Ignore"

Then configure an automation to listen for the mobile_app_notification_action event. When it receives action: "OPEN_DOOR", the automation can run the action that opens the door, wherever you are in the world. Anything that unlocks or opens an entrance is security-sensitive, so add appropriate safeguards before enabling it.

Two common pitfalls:
  1. Android allows no more than 3 action buttons in a notification; iOS supports about 10, but you may need to expand the notification to see the additional buttons. For cross-platform notifications, use no more than 3.
  2. Action IDs must be globally unique. If two doorbells both use action: OPEN_DOOR, selecting either notification will trigger the same automation. To prevent this, incorporate {{ context.id }} or prefix the ID with the device or location name—for example, action: OPEN_DOOR_FRONT.

Tags and groups: Manage multiple notifications

  • tag: laundry: A later notification with the same tag will replace the previous one—for example, as the washing machine moves from washing to spinning to complete.
  • group: security: Notifications in the same group will be stacked together, so doorbell and alarm notifications can appear in one stack.
Coming in an advanced guide: A camera event can trigger a notification with a snapshot and action buttons such as “Record for 30 seconds” or “Call the police.” These topics are reserved for a future tutorial series.

Frequently asked questions

Why did my notification not arrive?
Check, in order: (1) the phone’s notification permission for the app; (2) Settings → Companion App → Notifications in the app; (3) the name of the action you ran; and (4) whether the phone is in Do Not Disturb mode.
Can I notify every phone in the household?
Yes. The special notify.notify action sends to its configured notification targets, so verify those targets before using it. Alternatively, create a named notification group for specific recipients.
Can I send notifications by email, Slack, or Telegram?
Yes. Home Assistant supports additional channels, including SMTP email and Telegram; Slack is another widely available option. LINE Notify has been discontinued, and using LINE now requires the Messaging API. For an international audience, email, Telegram, or Slack are more broadly applicable alternatives. Start with the Companion App, then add another channel as a backup if needed.

Troubleshooting

My phone does not receive notifications
Check, in order: (1) the Companion App has notification permission; (2) the phone is not in Airplane Mode, Do Not Disturb, or a restrictive power-saving mode; (3) the Home Assistant server has internet access, because the app relies on Firebase Cloud Messaging or the Apple Push Notification service (APNs); and (4) the action name is correct. Search for notify.mobile_app under Settings → Tools → Actions and confirm that your phone is listed.
My iOS notification arrives without sound
Check the Home Assistant notification sound settings in iOS and any active Focus mode. If you use a custom sound, make sure it is installed in the app and referenced correctly under push: and sound: in the notification data.
Notifications arrive at home but not while I am away
Companion App notifications use Firebase Cloud Messaging or APNs. As long as your phone has internet access, receiving a notification does not require Nabu Casa or dynamic DNS (DDNS). You only need remote access when using the app to control Home Assistant while away; see the appendix.