{"id":49754170,"url":"https://github.com/rjullien/ha-notification-manager","last_synced_at":"2026-06-14T07:03:07.630Z","repository":{"id":356907773,"uuid":"1234527179","full_name":"rjullien/ha-notification-manager","owner":"rjullien","description":"Home Assistant custom component - Notification Manager (Alexa TTS, Phone, Telegram, WhatsApp via whatsmeow bridge). HACS compatible.","archived":false,"fork":false,"pushed_at":"2026-06-09T22:00:55.000Z","size":108,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T23:19:52.474Z","etag":null,"topics":["alexa","hacs","home-assistant","homeassistant","notification","telegram","tts","whatsapp"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rjullien.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-10T09:54:04.000Z","updated_at":"2026-06-09T21:57:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rjullien/ha-notification-manager","commit_stats":null,"previous_names":["rjullien/ha-notification-manager"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/rjullien/ha-notification-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rjullien%2Fha-notification-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rjullien%2Fha-notification-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rjullien%2Fha-notification-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rjullien%2Fha-notification-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rjullien","download_url":"https://codeload.github.com/rjullien/ha-notification-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rjullien%2Fha-notification-manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34312137,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alexa","hacs","home-assistant","homeassistant","notification","telegram","tts","whatsapp"],"created_at":"2026-05-10T17:20:32.743Z","updated_at":"2026-06-14T07:03:07.625Z","avatar_url":"https://github.com/rjullien.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Notification Manager for Home Assistant\n\n[![HACS Badge](https://img.shields.io/badge/HACS-Custom-orange.svg)](https://github.com/custom-components/hacs)\n[![GitHub Release](https://img.shields.io/github/release/rjullien/ha-notification-manager.svg)](https://github.com/rjullien/ha-notification-manager/releases)\n\nA production-grade Home Assistant custom component for multi-channel notifications. Supports **Alexa TTS** (with automatic volume save/restore), **mobile push**, **Telegram**, and **WhatsApp** via [whatsmeow-bridge](https://github.com/tulir/whatsmeow).\n\n---\n\n## Features\n\n| Channel | What it does |\n|---------|-------------|\n| 📱 **Phone (push)** | iOS/Android push via `notify.mobile_app_*` |\n| 💬 **Telegram** | Direct message via `telegram_bot.send_message` |\n| 🔊 **Alexa TTS** | Multi-room TTS with automatic volume save → set → restore |\n| 🟢 **WhatsApp** | REST API calls to whatsmeow-bridge |\n| 📡 **Status sensor** | `sensor.notification_manager_whatsapp_status` (polls every 5 min) |\n\n---\n\n## Requirements\n\n- Home Assistant **2024.12+**\n- [Alexa Media Player](https://github.com/custom-components/alexa_media_player) integration (for Alexa TTS)\n- [Telegram Bot](https://www.home-assistant.io/integrations/telegram_bot/) integration (for Telegram)\n- Mobile Companion App installed on target phones\n- [whatsmeow-bridge](https://github.com/tulir/whatsmeow) running and accessible (for WhatsApp)\n\n\u003e Since v1.6.0 the `input_text.media_player_volumes` helper is **no longer needed** — volumes are kept in memory during the TTS cycle (the helper was written but never read back, and overflowed its 255-char limit beyond ~8 players).\n\n---\n\n## Installation\n\n### Via HACS (recommended)\n\n1. Open HACS → Integrations → ⋮ → Custom repositories\n2. Add `https://github.com/rjullien/ha-notification-manager` as **Integration**\n3. Search for \"Notification Manager\" and install\n4. Restart Home Assistant\n\n### Manual installation\n\n1. Copy `custom_components/notification_manager/` into your HA `custom_components/` directory\n2. Restart Home Assistant\n\n---\n\n## Configuration\n\n1. Go to **Settings → Devices \u0026 Services → Add Integration**\n2. Search for **Notification Manager**\n3. Enter your whatsmeow-bridge URL and bearer token\n4. **Verify TLS certificate** is enabled by default — disable it only if your bridge uses a self-signed certificate\n\n\u003e **No WhatsApp?** You can enter any placeholder URL — the component works fine for phone/Alexa even if the bridge is down.\n\n---\n\n## Service: `notification_manager.notify`\n\n### Parameters\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `message_tel` | string | `\"\"` | Message for push/Telegram/WhatsApp |\n| `message_alexa` | string | `\"\"` | TTS message for Alexa (primary language) |\n| `message_alexa_en` | string | `\"\"` | TTS message for English Echo devices (sent after 3s delay) |\n| `notification_tel` | string | `\"all\"` | Phone targets — person names (space-separated) or `\"none\"` |\n| `notification_whatsapp` | string | `\"none\"` | WhatsApp targets — person names (space-separated) or `\"none\"` |\n| `notification_alexa` | string | `\"\"` | Alexa targets — keywords matched against entity IDs (space-separated) or `\"aucun\"` |\n\n### Target resolution\n\n**Phone/Telegram** (`notification_tel`):\n- Space-separated **person names** (case-insensitive)\n- `\"all\"` or empty → sends to default targets list\n- `\"none\"` / `\"aucun\"` → skip\n- Names are resolved against `PHONE_TARGETS` dict\n\n**WhatsApp** (`notification_whatsapp`):\n- Space-separated **person names** (case-insensitive)\n- `\"none\"` / `\"aucun\"` / empty → skip\n- Names are resolved against `WHATSAPP_CONTACTS` dict\n\n**Alexa** (`notification_alexa`) — pattern matching:\n- Space-separated **keywords** matched as substrings against `media_player.*` entity IDs\n- Example: `\"show\"` → matches all entities containing \"show\" (e.g. `media_player.rene_echo_show_2`)\n- Example: `\"salon chambre\"` → matches entities containing \"salon\" OR \"chambre\"\n- Empty → defaults to keyword `\"show\"` (Echo Show devices)\n- `\"aucun\"` / `\"none\"` / `\"off\"` → skip\n- ⚠️ **No `\"all\"` keyword** — speakers span multiple locations, broadcasting everywhere is forbidden\n\n\u003e The algorithm is inherited from the original mamagetts automation: substring matching gives flexibility without maintaining a separate name→entity mapping.\n\n---\n\n## Usage examples\n\n### Basic notification — all channels\n\n```yaml\nservice: notification_manager.notify\ndata:\n  message_tel: \"The delivery has arrived\"\n  message_alexa: \"Your delivery is here!\"\n  notification_tel: \"all\"\n  notification_alexa: \"\"\n```\n\n### Specific person, push + WhatsApp\n\n```yaml\nservice: notification_manager.notify\ndata:\n  message_tel: \"Your package is at the door\"\n  notification_tel: \"John\"\n  notification_whatsapp: \"John\"\n```\n\n### Alexa announcement in specific rooms\n\n```yaml\nservice: notification_manager.notify\ndata:\n  message_alexa: \"Dinner is ready!\"\n  notification_alexa: \"kitchen bedroom\"\n  notification_tel: \"none\"\n```\n\n---\n\n## Sensor: `sensor.notification_manager_whatsapp_status`\n\n| State | Meaning |\n|-------|---------|\n| `connected` | Bridge is up and responding |\n| `disconnected` | Bridge unreachable or returned error |\n| `unknown` | Bridge URL not configured or not yet polled |\n\nPolls every **5 minutes**. Use in automations to alert when WhatsApp goes down.\n\n---\n\n## Alexa TTS — volume management\n\n1. **Read** current volume from each target entity (kept in memory)\n2. **Set** all targets to TTS volume (default `0.7`) — awaited *before* TTS so speech never starts at the old level\n3. **Send** TTS via `notify.alexa_media`\n4. **Wait** configurable delay (default `8s`)\n5. **Restore** each player to its saved volume\n\nThe full cycle is serialised behind a lock: overlapping `notify` calls queue up instead of capturing the TTS volume as the \"original\" one. The English message (`message_alexa_en`) runs as an independent task with its own 3 s delay — it is never delayed by slow channels (e.g. WhatsApp retries).\n\n---\n\n## Customization\n\nEdit `custom_components/notification_manager/const.py` to configure:\n\n- `ALEXA_PLAYERS` — list of all Alexa `media_player.*` entity IDs\n- `PHONE_TARGETS` — mobile app service names and Telegram chat IDs per person\n- `WHATSAPP_CONTACTS` — WhatsApp JIDs per person\n- `ALEXA_TTS_VOLUME` — TTS volume level (default `0.7`)\n- `ALEXA_POST_TTS_DELAY` — wait after TTS before restoring volume (default `8s`)\n\n---\n\n## Troubleshooting\n\n| Issue | Fix |\n|-------|-----|\n| Service not available | Restart HA; check logs for `notification_manager` |\n| Alexa TTS not working | Verify Alexa Media Player integration + entity IDs in `const.py` |\n| WhatsApp not delivered | Check `sensor.notification_manager_whatsapp_status`; verify bridge URL/token |\n| Volume not restored | Restore manually if HA restarted mid-TTS (volumes are held in memory during the cycle) |\n\n---\n\n## Security notes\n\n- **TLS verification is on by default** (v1.6.0). Disable it per-entry in the config flow only for self-signed bridge certificates.\n- The diagnostic services `whatsapp_bridge_logs` and `whatsapp_bridge_restart` are **restricted to administrator users** (bridge logs may contain phone numbers and message contents).\n- The status sensor no longer exposes the bridge URL as a state attribute.\n- Tailscale MagicDNS hostnames are resolved **in-process** via `TAILSCALE_DNS_OVERRIDES` (see `const_private.example.py`) — `/etc/hosts` is never modified.\n- Keep all personal data (names, chat IDs, JIDs) in `/config/notification_manager_private.py`; never commit it.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frjullien%2Fha-notification-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frjullien%2Fha-notification-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frjullien%2Fha-notification-manager/lists"}