Home Assistant

Minara のアラートを任意の Home Assistant の notify.* ターゲット（モバイルプッシュ、TTS、メール、Pushover など）にルーティングします。

🟢 実行環境対応済み HA の notify.* サービスドメインを通じて通知をファイア&フォゲット方式で送信します。送信専用です。notify.* はワンショットでメッセージ ID を返さないため、編集はできません。ヘルパーは token をバッファリングし、ファイナライズ時にまとめて送信します。

提供される機能

任意の notify.* ターゲット （Home Assistant が到達できるもの）:
- mobile_app_<device>: HA コンパニオンアプリ経由の iOS / Android プッシュ通知
- alexa_media_<device>: Echo デバイスへのアナウンス
- google_assistant_sdk: Google Home を通じた TTS
- pushover / telegram / discord: HA インテグレーション経由でプロキシ
- tts.* サービス: HA 音声スタックで音声出力
- YAML で定義したカスタムの notify.* サービスにも対応
デフォルトはチャネルなし。メッセージのルーティングは HA サービスが担うため、channel の上書き指定は無視されます（HA サービス ID はゲートウェイ作成時に設定されます）
ソフトリミットは 4,096 文字（ヘルパーのデフォルト値）。HA 自体にはハード制約はありません

セットアップ

1. 長期アクセストークンの作成

Home Assistant の UI を開きます
画面左下のアバターをクリックし、Long-lived access tokens を選択します
Create Token をクリックし、名前を「Minara」にして、表示されるトークンをコピーします（表示は一度のみ）

2. notify サービスの選択

HA の Developer Tools → Services を開き、サービスピッカーに notify. と入力します。動作するものを選んでください。モバイルプッシュが一般的な出発点です:

notify.mobile_app_your_phone

Minara と接続する前に、UI から直接テストメッセージを送信し、ターゲットに到達できることを確認してください。

3. Minara の設定

minara auth messaging add home_assistant

またはプロジェクトルートの .env ファイルに直接記述します:

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

HASS_URL はベース URL をフルで指定し、末尾のスラッシュは不要です。HASS_NOTIFY_SERVICE の notify. プレフィックスは任意です。ゲートウェイがどちらの場合も自動で除去します。

4. テスト

minara auth messaging test home_assistant

テスト用のピングが、設定した notify ターゲットに届きます。Alexa TTS サービスを選んだ場合はスピーカーがメッセージを読み上げ、プッシュ通知を選んだ場合はスマートフォンが振動します。

notify ルートの例

用途	`HASS_NOTIFY_SERVICE`	備考
スマートフォンへのプッシュ（iOS/Android）	`mobile_app_<device>`	HA コンパニオンアプリとプッシュ通知の有効化が必要
部屋へのアナウンス（Echo）	`alexa_media_<device>`	HACS の alexa_media_player インテグレーションが必要
Google Home 経由の TTS	`google_assistant_sdk`	google_assistant_sdk インテグレーションが必要
Pushover へのエスカレーション	`pushover`	インテグレーション: `notify.pushover_*`
Telegram への転送	`telegram`	HA → Telegram が設定済みの場合に利用可能。Minara → HA → Telegram という間接構成になりますが、ルーティングを HA に集約できます
グループへの一括配信	YAML の `notify.grouped_alerts:` ファンアウト	`configuration.yaml` でグループを定義し、ここで参照します

チャネル上書きが不可な理由

HA はメッセージターゲット ID ではなく notify サービス ID にルーティングします。複数のターゲットにファンアウトしたい場合は、HA の YAML でグループサービスを作成してください:

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

その後 HASS_NOTIFY_SERVICE=grouped_alerts を指定すると、Minara からの1件のアラートがすべてのサービスにファンアウトされます。

トラブルシューティング

「401 Unauthorized」

HASS_TOKEN が誤っているか、失効しています。HA の Profile → Long-lived access tokens で再生成してください

「404 Not Found: service not found」

HASS_NOTIFY_SERVICE がこの HA インスタンスに存在しません。Developer Tools → Services で確認してください。notify ドメインには現在登録済みのサービスのみ表示されます

「TLS エラー / 証明書が拒否される」

HASS_URL に自己署名証明書が使われています。システムのトラストストアに証明書を追加するか、Caddy / Traefik / Cloudflare Tunnel を経由して正規の証明書を適用してください

「HA にはメッセージが届いたが通知が来ない」

モバイルアプリの場合: コンパニオンアプリのプッシュ通知が無効になっているか、端末がおやすみモードになっている可能性があります。HA の UI から同じサービスを直接呼び出して切り分けてください。そちらも失敗する場合は HA 側の問題です

リファレンス

環境変数: HASS_URL, HASS_TOKEN, HASS_NOTIFY_SERVICE
ソース: apps/agent/src/messaging/home_assistant.ts
HA REST API: developers.home-assistant.io/docs/api/rest

目次