Home Assistant Notifications: Push Alerts to Your Phone

If you use Home Assistant, notifications are the difference between knowing your garage opened and finding out hours later — and a working Home Assistant setup is all you need to send your first phone push in under ten minutes. The hard part isn't hitting send; it's making sure the alert actually surfaces on the right phone at the right time.

Most failures aren't in Home Assistant. They happen because a phone's notification channel, Focus mode, battery optimization, or push path blocks or delays an otherwise valid alert. This guide treats those as first-class problems instead of afterthoughts.

You'll set up the Companion App, identify the correct notify target, test a plain notification, then build groups, scripts, and actionable buttons. From there, you'll learn how Android and iOS handle urgency differently, and how to keep routine alerts from becoming noise.

This is written for Home Assistant users who want local-first, no-subscription reliability — whether you're just getting started or already have dozens of automations that need smarter phone alerts.

Disclosure: This post contains affiliate links. We may earn a commission when you buy through them, at no extra cost to you.

What You'll Need

• A running Home Assistant instance — no new hardware is required for notifications
• The official Home Assistant Companion App installed on Android or iPhone
• The phone registered in Home Assistant through the Mobile App integration
• Network access to Home Assistant, either locally or via remote access if you want push while away
• A known notify target — either a notification entity or a legacy notify.mobile_app_<device> action

Before You Start — "Sent" Is Not the Same as "Shown"

Home Assistant's notification path looks like a single action, but it includes two independent handoffs. The first is Home Assistant handing a payload to the Companion App through a notify target. The second is the phone's operating system deciding how or when to present it.

On Android, notification channels, battery optimization, and Do Not Disturb can suppress or delay an alert. On iOS, Focus modes and interruption levels can hide or mute it. Standard remote push also uses cloud infrastructure, while Local Push uses your own connection — and the two behave differently under load, privacy expectations, and daily quotas.

Because of this, the first diagnostic should always be a deliberately boring notification to one known phone — not a complex automation with templates and conditions. That isolates registration and OS permissions from trigger mistakes. A sent notification is not necessarily a displayed notification.

Step 1 — Install and Register the Companion App

Install the official Home Assistant Companion App from Google Play or the App Store. Open it, point it at your Home Assistant URL, and sign in with your Home Assistant account.

On first successful login, the app registers itself and creates a device in Home Assistant. You should see it under Settings → Devices & Services → Mobile App. That registration is the root of most later problems: if the phone no longer appears there, notifications cannot route.

Current Android releases require Android 6.0 / API 23 or later. Recent iOS releases have raised the minimum supported version, so keep the app reasonably up to date. Registration does not require a paid subscription.

Step 2 — Send Your First Test Notification

Start from Home Assistant's Settings → Tools → Actions page.

1. Choose the notify.send_message action.
2. Target a specific notify entity or legacy action — not the generic notify.notify shorthand.
3. Enter a message such as Hello Home Assistant.
4. Run the action.

If the alert appears on the intended phone, the core path works. If it doesn't, check phone notification permissions and the app's registration before touching any automation. Home Assistant's notify.persistent_notification target shows a message inside the Home Assistant interface, not on a phone — don't confuse the two when testing.

Step 3 — Identify the Correct Notification Target

One of the most common beginner problems isn't writing the message; it's knowing which notifier represents which phone.

Since Home Assistant 2026.5, Mobile App devices expose notification entities that can be addressed with notify.send_message using target: entity_id. The older action-based names still work, and still appear throughout existing tutorials and forum posts. Both are valid, but they are not interchangeable in every configuration.

The legacy action name is tied to the device identifier. If you rename or replace a device, the old action can stop matching your intention. Use a specific target whenever delivery to a particular phone matters.

Step 4 — Group Recipients and Build Reusable Scripts

When more than one person in the household should receive alerts, don't edit every automation individually. Create a group.

Modern Home Assistant lets you create a regular Group helper through the UI and place the device-backed notification entities inside it. You can then target that group like any other notify target. Legacy setups can define an action-based group in YAML:

notify:
  - platform: group
    name: household_phones
    services:
      - service: mobile_app_pixel_8
      - service: mobile_app_iphone_15

A group is for fan-out: send the same message to multiple destinations. A script is for reusable behavior. Use a script when you want common title/data structure, conditional recipients, severity routing, or a single place to change how notifications are sent.

notify_household:
  fields:
    message:
      required: true
      selector:
        text:
    title:
      selector:
        text:
  sequence:
    - action: notify.send_message
      target:
        entity_id:
          - notify.pixel_8
          - notify.iphone_15
      data:
        title: "{{ title }}"
        message: "{{ message }}"

A plain group cannot express "notify whoever is home" or apply per-person preferences. That's where scripts and Home Assistant automations take over.

Step 5 — Add Actionable Buttons That Return Events

Actionable notifications attach one or more buttons to an alert. Pressing a button sends a mobile_app_notification_action event back to Home Assistant. That event does not directly call a service — an automation or script has to catch it and act.

- action: notify.send_message
  target:
    entity_id: notify.pixel_8
  data:
    title: "Motion in garage"
    message: "The garage camera detected motion."
    data:
      actions:
        - action: snapshot
          title: "Send camera snapshot"
        - action: ignore
          title: "Ignore"

To respond to the button, use a wait_for_trigger on mobile_app_notification_action after sending the notification. Use a unique action identifier for each script execution when several notifications could be waiting at once, and always set a timeout so the script doesn't hang forever.

Android supports up to three notification actions per alert. iOS can display more, but long action lists become unwieldy. When a script waits for a response, choose its script mode intentionally — single, restart, queued, or parallel — because that determines what happens when a second actionable notification arrives while the first is still waiting.

Step 6 — Control Urgency on Android and iOS

Android and iOS handle notification urgency through completely different mechanisms.

On Android, notification channels determine sound, vibration, importance, and Do Not Disturb behavior per category. Channel characteristics are largely set when the channel is first created, and later user changes in Android settings override Home Assistant's preferences. For genuinely urgent cloud push, the Companion documentation recommends ttl: 0 plus priority: high. Android's Doze and battery optimization can otherwise defer normal delivery.

On iOS, interruption levels are the lever. time-sensitive notifications can break through Focus settings. critical alerts can additionally play sound despite mute and Do Not Disturb, and are exempt from the ordinary push quota. They should be reserved for events where a delay or silence genuinely matters — not as a default for routine smart-home chatter.

Both platforms support tags. Reusing the same tag replaces the previous alert instead of stacking duplicates, which is perfect for stateful conditions like "garage open for 10 minutes" becoming "garage open for 20 minutes."

Step 7 — Choose Between Cloud Push and Local Push

Standard Companion push uses Home Assistant's remote infrastructure and Apple/Google push services. It works anywhere the phone has internet, but it is limited to 500 push notifications per device per day, resetting at midnight UTC. Failed delivery attempts, Critical Alerts, and Notification Commands don't consume that allowance. Home Assistant says it does not store notification content on its remote servers, but the push provider can still process the content — so standard cloud push is not end-to-end encrypted inside that path.

Local Push uses the Home Assistant WebSocket API instead of APNs or FCM. It requires Home Assistant Core 2021.6 or newer, and only works while the Companion App considers itself connected to your Home Assistant internal URL. Local Push notifications do not count against the 500-per-day quota. On Android, a persistent WebSocket connection keeps Local Push reachable more consistently but increases battery use.

The practical result: you can keep Home Assistant fully local while ordinary phone notifications still use external push infrastructure. That's a privacy distinction worth understanding, not a failure of your setup. Test both paths explicitly when diagnosing problems. Many users run both — cloud push for remote, Local Push for home — and that's a legitimate configuration.

Step 8 — Troubleshoot Missing, Delayed, or Duplicate Notifications

Start with a plain test notification to a specific notify entity. If that works, the problem is in your automation or payload. If it doesn't, the problem is in registration, permissions, or the push path.

The confirmation: true option returns a mobile_app_notification_received event when the app receives the notification. It confirms device receipt — not that a person read or acknowledged the alert. Android can also report manual dismissal through mobile_app_notification_cleared, but that is not available on iOS.

Common Mistakes to Avoid

• Using notify.notify as a default target instead of an explicit phone.
• Assuming a successfully sent notification will always be displayed.
• Debugging complex YAML before testing the simplest possible payload.
• Marking every alert as critical or high priority, which teaches phones to ignore you.
• Expecting actionable buttons to directly call services — they only return events.
• Forgetting to choose a script mode when waiting for actionable responses.
• Not tagging stateful alerts, causing a stream of duplicate notifications.

Frequently Asked Questions

Conclusion

Reliable Home Assistant notifications are less about the perfect YAML and more about understanding the two handoffs: Home Assistant must reach the right phone, and the phone must decide to show the alert. Nail the plain test first, then layer on groups, scripts, and actions.

Use modern notification entities for new work, but don't be surprised when older tutorials use legacy action names. Understand the difference between cloud push and Local Push, and reserve urgency levels for events that actually warrant them.

If you're ready to build on this foundation, start with the Home Assistant automations guide, plan your remote access strategy, or revisit your Home Assistant hardware options to make sure the whole system stays responsive.