Home Assistant Companion App: Phone Notifications Setup

To send phone notifications from Home Assistant, you install the official Home Assistant Companion app on your phone, sign in to your Home Assistant server, and then call the notify service it creates (something like notify.mobile_app_yourphone) from an automation or script. The Companion app is the only supported way to get true push notifications straight to iOS and Android — no third-party bridge required. Once the app is connected, your server can push alerts, sounds, images, and even tappable action buttons to your lock screen.

This guide walks through the setup end to end, then covers the extras — actionable notifications, critical alerts, and the fixes for the classic “why is nothing arriving” problem. If you only want the short version of getting alerts working, our companion piece on how to get phone notifications from Home Assistant covers the essentials.

Before you start: what you need

The Companion app talks to your Home Assistant instance over your network. A few requirements make the difference between notifications that work everywhere and ones that only fire at home.

• A running Home Assistant server. If you haven't set one up yet, see our beginner's install guide.
• The official Companion app from the Apple App Store or Google Play. Avoid unofficial clones — only the official app registers a working push channel.
• A way to reach your server from outside the house if you want alerts on cellular. Home Assistant Cloud (Nabu Casa) is the simplest; a self-hosted reverse proxy or VPN also works. Push delivery itself routes through Apple and Google servers, but the app must be able to register with your instance first.

Step 1: Install and connect the Companion app

1. 1Install the official Home Assistant app on your phone
2. 2Enter your server URL and sign in with your user account
3. 3Allow notification permission when the app prompts
4. 4Confirm a new notify.mobile_app_* service exists in Developer Tools

1. Install the app and open it. On first launch it can auto-discover a server on your local network, or you can type the URL manually (for example https://yourname.ui.nabu.casa or your local http://homeassistant.local:8123).
2. Sign in with your Home Assistant username and password. Each phone that signs in becomes its own device.
3. When your phone asks whether to allow notifications, say yes. This is the single most common reason alerts silently fail later — the OS permission was never granted.
4. Verify the connection. Go to Developer Tools → Actions (formerly Services) on your server and search for notify. You should see an entry named after your device, such as notify.mobile_app_pixel_8.

Step 2: Send your first test notification

Before wiring anything into an automation, confirm the pipe works. In Developer Tools → Actions, pick your notify.mobile_app_* service, switch to YAML mode, and run this:

action: notify.mobile_app_pixel_8
data:
  title: "Test alert"
  message: "Hello from Home Assistant"

Your phone should buzz within a second or two. If it does, the hard part is done — everything else is just deciding when to fire.

Step 3: Trigger notifications from automations

Now put that service inside an automation so it fires on real events. The pattern is identical: a trigger, optional conditions, then the notify action. Here's a door-left-open example:

alias: Notify when front door left open
triggers:
  - trigger: state
    entity_id: binary_sensor.front_door
    to: "on"
    for:
      minutes: 5
actions:
  - action: notify.mobile_app_pixel_8
    data:
      title: "Front door"
      message: "Open for 5 minutes"

If you're new to building these, our automations for beginners guide explains triggers and conditions in depth. You can also combine notifications with presence detection so alerts only fire when nobody's home.

Going further: rich and actionable notifications

The Companion app supports far more than plain text. You attach these through the data block, and support differs slightly between platforms.

An actionable notification looks like this:

action: notify.mobile_app_pixel_8
data:
  message: "Front door is unlocked"
  data:
    actions:
      - action: "LOCK_DOOR"
        title: "Lock it"

When the user taps Lock it, the app fires a mobile_app_notification_action event carrying LOCK_DOOR. A second automation triggers on that event and locks the door. This event-driven pattern is what turns a notification into a remote control.

Fixing notifications that don't arrive

When alerts stop, the cause is almost always one of a short list. Work through them in order.

1. OS permission was denied or revoked. Check your phone's system settings for the Home Assistant app and confirm notifications are allowed.
2. Battery optimization is killing the app. On Android especially, aggressive power management can suspend the push channel. Exclude the app from battery optimization.
3. The service name changed. If you renamed the phone, the old notify.mobile_app_* entity no longer exists and the automation errors silently.
4. The server can't be reached. Push registration depends on the app having connected. Confirm remote access works.
5. Do Not Disturb is swallowing them. Use a critical/time-sensitive notification for genuinely urgent alerts so they override DND.

It's also worth keeping a current backup of your Home Assistant config before you build a large stack of notification automations, so a bad edit is easy to roll back.

Frequently asked questions

Do I need Nabu Casa to get notifications?

No. Home Assistant Cloud makes remote access effortless, but any working remote connection — a reverse proxy or VPN — lets the Companion app register for push. The push messages themselves travel over Apple's and Google's networks, not directly from your server.

Why do notifications work at home but not on cellular?

This almost always means your phone can only reach the server on the local network. Set up remote access so the app stays registered when you're away. Local-only URLs can't sustain the push channel off-network.

Can I send a notification to just one family member?

Yes. Each phone creates its own notify.mobile_app_* service, so you target an individual by calling that specific service. To reach several at once, define a notification group that bundles multiple device services under one name.

Do I need HACS or add-ons for this?

No — phone notifications are built into the core Companion app integration. HACS and add-ons only come into play if you want extra dashboards or custom cards, not for basic push alerts.

Sources

• Home Assistant — official documentation
• Home Assistant Companion App documentation