Home Assistant

Route Minara alerts through any Home Assistant notify.* target — mobile push, TTS, email, pushover, and more.

🟢 Runtime-ready — fire-and-forget notifications via HA's notify.* service domain. Send-only: notify.* is one-shot and doesn't return a message id, so editing is impossible. The helper buffers tokens and sends once at finalize time.

What you get

Any notify.* target Home Assistant can reach:
- mobile_app_<device> — iOS / Android push via the HA companion app
- alexa_media_<device> — announce via an Echo device
- google_assistant_sdk — TTS through a Google Home
- pushover / telegram / discord proxied through HA integrations
- tts.* services — speak via your HA voice stack
- Any custom notify.* service you've defined in YAML
Channel-less by default — HA service routes the message; the channel override is ignored (HA service id is set at gateway creation time)
4 096-char soft limit (helper default); HA itself has no hard limit

Setup

1. Create a long-lived access token

Open your Home Assistant UI
Click your avatar (bottom-left) → Long-lived access tokens
Create Token → name it "Minara" → copy the token (shown once)

2. Pick a notify service

In HA, go to Developer Tools → Services and type notify. into the service picker. Pick one that works — mobile push is the common starting point:

notify.mobile_app_your_phone

Fire the service with a test message directly in the UI to confirm the target is reachable before wiring Minara.

3. Configure Minara

minara auth messaging add home_assistant

Or directly in your project .env file:

HASS_URL=https://hass.example:8123
HASS_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
HASS_NOTIFY_SERVICE=mobile_app_your_phone

HASS_URL should be the full base URL, no trailing slash. The notify. prefix on HASS_NOTIFY_SERVICE is optional — the gateway strips it either way.

4. Test

minara auth messaging test home_assistant

The test ping lands on whichever notify target you picked. If you picked an Alexa TTS service, the speaker will say the message out loud. If you picked push, the phone buzzes.

Example notify routes

Intent	`HASS_NOTIFY_SERVICE`	Notes
Phone push (iOS/Android)	`mobile_app_<device>`	Needs HA companion app + push enabled
Announce in a room (Echo)	`alexa_media_<device>`	Needs alexa_media_player HACS integration
TTS through Google Home	`google_assistant_sdk`	Needs google_assistant_sdk integration
Pushover escalation	`pushover`	Integration: `notify.pushover_*`
Re-route into Telegram	`telegram`	If you already have HA → Telegram set up; Minara → HA → Telegram is indirection but lets you centralise routing in HA
Broadcast to a group	a YAML `notify.grouped_alerts:` fan-out	Define the group in `configuration.yaml` and reference it here

Why no channel override

HA routes to a notify service id, not to a message-target id. If you want to fan out, create a YAML group service in HA:

# configuration.yaml
notify:
  - platform: group
    name: grouped_alerts
    services:
      - service: mobile_app_pixel
      - service: alexa_media_kitchen

Then point HASS_NOTIFY_SERVICE=grouped_alerts and a single Minara alert fans out to every service.

Troubleshooting

"401 Unauthorized"

HASS_TOKEN is wrong or revoked. Regenerate it in HA → Profile → Long-lived access tokens

"404 Not Found — service not found"

HASS_NOTIFY_SERVICE doesn't exist in this HA instance. Check it in Developer Tools → Services; the notify domain shows only services that are currently registered

"TLS error / certificate rejected"

Self-signed cert on HASS_URL. Either install the cert in the system trust store, or front HA with a real cert via Caddy / Traefik / Cloudflare Tunnel

"Message went to HA but no notification arrived"

Mobile app: push isn't enabled for the companion app, or the device is in Do Not Disturb. Trigger the same service from the HA UI to isolate: if that fails too, it's HA-side

Reference

Env vars: HASS_URL, HASS_TOKEN, HASS_NOTIFY_SERVICE
Source: apps/agent/src/messaging/home_assistant.ts
HA REST API: developers.home-assistant.io/docs/api/rest

On this page