{"id":43250706,"url":"https://github.com/txxa/hass-ans","last_synced_at":"2026-06-15T09:00:37.338Z","repository":{"id":325872795,"uuid":"1072536105","full_name":"txxa/hass-ans","owner":"txxa","description":"Home Assistant integration for intelligent, centralized notification routing with advanced filtering, rate limiting, retries, and multi-channel delivery.","archived":false,"fork":false,"pushed_at":"2026-06-10T22:34:16.000Z","size":724,"stargazers_count":38,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T00:09:51.282Z","etag":null,"topics":["advanced-notification-system","ans","hacs","hacs-custom","hacs-integration","home-assistant","home-assistant-custom","home-assistant-integration","notification-system"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/txxa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":"2025-10-08T21:24:10.000Z","updated_at":"2026-06-05T21:08:01.000Z","dependencies_parsed_at":null,"dependency_job_id":"7383606c-4a79-45e1-8a61-d239e1444723","html_url":"https://github.com/txxa/hass-ans","commit_stats":null,"previous_names":["txxa/hass-ans"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/txxa/hass-ans","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txxa%2Fhass-ans","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txxa%2Fhass-ans/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txxa%2Fhass-ans/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txxa%2Fhass-ans/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/txxa","download_url":"https://codeload.github.com/txxa/hass-ans/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txxa%2Fhass-ans/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34355156,"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-15T02:00:07.085Z","response_time":63,"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":["advanced-notification-system","ans","hacs","hacs-custom","hacs-integration","home-assistant","home-assistant-custom","home-assistant-integration","notification-system"],"created_at":"2026-02-01T13:00:56.280Z","updated_at":"2026-06-15T09:00:37.283Z","avatar_url":"https://github.com/txxa.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Advanced Notification System (ANS) for Home Assistant\n\n[![GitHub Release](https://img.shields.io/github/release/txxa/hass-ans.svg?style=for-the-badge)](https://github.com/txxa/hass-ans/releases)\n[![GitHub Activity](https://img.shields.io/github/commit-activity/y/txxa/hass-ans.svg?style=for-the-badge)](https://github.com/txxa/hass-ans/commits/main)\n[![License](https://img.shields.io/github/license/txxa/hass-ans.svg?style=for-the-badge)](https://github.com/txxa/hass-ans/blob/main/LICENSE)\n[![HACS](https://img.shields.io/badge/HACS-Custom-orange.svg?style=for-the-badge)](https://hacs.xyz/docs/faq/custom_repositories)\n\n_A sophisticated notification management system for Home Assistant with advanced routing, filtering, and delivery control._\n\nANS is a custom Home Assistant integration that acts as a centralized notification hub. Instead of calling `notify.mobile_app_*`, `notify.signal`, or TTS services individually from each automation, you make a single `ans.send_notification` call and ANS handles the rest: routing to the right recipients, choosing the right channels based on criticality, applying Do Not Disturb schedules, rate limiting, retrying on failure, and managing TTS volume.\n\n## Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Quick Start](#quick-start)\n- [Troubleshooting](#troubleshooting)\n- [Advanced Topics](#advanced-topics)\n- [Development and Maintenance](#development-and-maintenance)\n- [Contributions](#contributions)\n\n## Features\n\n- **Single service call** routes to all configured recipients and channels simultaneously\n- **Criticality-based channel mapping** — LOW through CRITICAL each trigger different channels per recipient\n- **Type and criticality filtering** per recipient (INFO, WARNING, ALERT, REMINDER, EVENT, SECURITY)\n- **Do Not Disturb** per recipient with configurable time windows and bypass rules for type and criticality\n- **Source blocking** via per-recipient regex patterns\n- **Rate limiting** — token bucket algorithm at both per-recipient and global level, with automatic retry queuing\n- **Queue depth limit** — configurable bounded delivery queue (default 500 tasks) prevents memory exhaustion under automation storms; excess tasks are dropped with a warning and a `ans_notification_failed` event\n- **Retry with exponential backoff** — configurable attempts and delays, with crash recovery across HA restarts\n- **Deduplication** — idempotent delivery prevents duplicate notifications, including duplicate TTS playback\n- **TTS via media player** — time-based and criticality-based volume control, automatic volume restoration, and per-device delivery lock to prevent overlapping playback\n- **Mobile app, Signal Messenger, persistent notification** support out of the box; Signal attachments are restricted to HA-managed directories (`config/`, `media/`, `www/`) to prevent path-traversal access; media URLs without a filename path segment (e.g. bare domains) are silently ignored with a warning log across all adapters; persistent notification image/video/file links use the filename as the label; extensible adapter architecture for additional channels\n- **Actionable mobile notifications** — include up to 3 action buttons in mobile push notifications via the `actions` field; button taps fire a `mobile_app_notification_action` HA bus event for automation response\n- **Acknowledgement tracking** — ANS tracks whether a delivered notification was acknowledged: tapping any action button on a mobile push, or dismissing a persistent notification in the HA sidebar, fires an `ans_notification_acknowledged` HA bus event and records the acknowledgement in a persistent `AcknowledgementRegistry`; automations can correlate the `notification_id` returned by `ans.send_notification` with this event to detect confirmed read receipts\n- **Audit log** — notification registry and delivery attempt logs with configurable retention (default 7 days, max 365 days) and hourly auto-purge\n- **Delivery outcome events** — `ans_notification_delivered`, `ans_notification_filtered`, `ans_notification_failed`, and `ans_notification_rate_limited` HA bus events let automations react to per-channel delivery results in real time\n- **Notification settled event** — `ans_notification_settled` fires once all fan-out tasks for a notification reach a terminal state, carrying per-recipient channel counts and a `recipients_delivered` total so automations can detect total delivery failure\n- **Stale channel Repairs issues** — when a `notify.*` service or `media_player.*` entity disappears from HA, ANS raises a HA Repairs issue in the UI with a clear remediation step; the issue is automatically dismissed when the channel recovers\n- **Service response** — `ans.send_notification` returns `{\"notification_id\": \"...\"}` for use with `response_variable`, enabling event correlation in automations\n- **Built-in diagnostics** panel for channel health and adapter status\n\nFor the full feature list, use cases, and requirements see [Overview](docs/overview.md).\n\n## Installation\n\n1. Add this repository as a custom repository to HACS: [![Add Repository](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=txxa\u0026repository=hass-ans\u0026category=integration)\n2. Use HACS to install the integration.\n3. Restart Home Assistant.\n4. Set up the integration using the UI: [![Add Integration](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=ans)\n\nFor manual installation see [Getting Started](docs/getting-started.md).\n\n## Configuration\n\n### Configuring the Integration\n\nTo add the integration, go to **Settings ➔ Devices \u0026 Services ➔ Integrations**, click ➕ Add Integration, and search for \"Advanced Notification System\" or \"ANS\".\n\nAfter installation, additional system-wide settings can be configured via the Options menu (**Settings ➔ Devices \u0026 Services ➔ Integrations ➔ Advanced Notification System ➔ Configure**).\n\nThe initial setup options (TTS Service, Enabled Channels, and Audit Logging) can be changed at any time using the Reconfigure flow (**Settings ➔ Devices \u0026 Services ➔ Integrations ➔ Advanced Notification System ➔ Reconfigure**).\n\n### Adding a Recipient\n\n1. Go to **Settings ➔ Devices \u0026 Services ➔ Integrations ➔ Advanced Notification System**\n2. Click **Add Recipient**\n3. Follow the configuration steps\n\nFor the full configuration walkthrough see [Getting Started](docs/getting-started.md).\n\n## Quick Start\n\nOnce installed and at least one recipient is configured, send your first notification:\n\n```yaml\nservice: ans.send_notification\ndata:\n  source: \"my_automation\"\n  title: \"Hello from ANS\"\n  message: \"ANS is working.\"\n  type: INFO\n  criticality: LOW\n```\n\n| Field | Required | Values |\n|---|---|---|\n| `source` | ✅ | any string — used for source-blocking filters |\n| `title` | ✅ | any string |\n| `message` | ✅ | any string |\n| `type` | ✅ | `INFO` `WARNING` `ALERT` `REMINDER` `EVENT` `SECURITY` |\n| `criticality` | ✅ | `LOW` `MEDIUM` `HIGH` `CRITICAL` |\n| `image` | ❌ | http/https URL or HA-relative path (e.g. `/local/img.jpg`, `/api/camera_proxy/camera.front`). Persistent notification: http/https renders as a clickable filename link; local path renders as an inline Markdown image embed. Mobile app: forwarded as push image (http/https only). Signal: forwarded as URL or attachment. URLs without a file path segment are ignored with a warning. |\n| `video` | ❌ | http/https URL or HA-relative path. Persistent notification: clickable filename link. Signal: forwarded as URL or attachment. Not supported by Mobile App. URLs without a file path segment are ignored with a warning. |\n| `file` | ❌ | http/https URL or HA-relative path. Persistent notification: clickable filename link. Signal: forwarded as URL or attachment. Not supported by Mobile App. URLs without a file path segment are ignored with a warning. |\n| `link` | ❌ | http/https URL. Mobile app: sets tap action (`data.url` / `data.clickAction`). Persistent notification: rendered as a `[Details]` link. Signal: appended to the message body. |\n| `context` | ❌ | key-value dict. Persistent notification: appended to the message body as a `Context:` section; values matching a known HA entity ID are auto-linked to their history page. Mobile app: the `entity` key sets a tap-action deep-link (`entityId:\u003centity_id\u003e`) when `link` is not set. Signal and TTS ignore all context keys. |\n| `actions` | ❌ | list of up to 3 action button dicts (`action`, `title`, optional `uri`) — forwarded to Mobile App only; ignored by other channels |\n| `channel_data` | ❌ | adapter-specific delivery overrides. Signal: supports `text_mode`, `attachments`, `urls`, `verify_ssl`. Mobile app: all keys are flat-merged into the `data:` payload (e.g. `{\"tag\": \"my-tag\"}` to control the notification tag for grouping or acknowledgement tracking). |\n\nFor real-world automation patterns see [Usage Examples](docs/usage-examples.md). For the full service reference and delivery pipeline see [How It Works](docs/how-it-works.md). For per-channel field handling, `channel_data` options, and acknowledgement mechanics see [Channel Reference](docs/channels.md).\n\n## Troubleshooting\n\nIf something isn't working as expected, the built-in diagnostics panel (**Settings ➔ Devices \u0026 Services ➔ Advanced Notification System ➔ ⋮ ➔ Download Diagnostics**) is the first place to look. For common issues and FAQ see [Troubleshooting](docs/troubleshooting.md).\n\n## Advanced Topics\n\nFor per-channel adapter reference (field handling, `channel_data`, acknowledgement) see [Channel Reference](docs/channels.md). For storage internals, crash recovery details, channel adapter lifecycle, and extension points see [Advanced Topics](docs/advanced.md).\n\n## Development and Maintenance\n\nI basically created this integration for my personal purpose. As it fulfils all my current needs I won't develop it further for now.\\\nHowever, as long as I am using this integration in my Home Assistant setup I will maintain it actively.\n\n## Contributions\n\nIf you want to contribute to this integration, please read the [Contribution guidelines](CONTRIBUTING.md)\n\n### Providing Translations for Other Languages\n\nIf you would like to use the integration in another language, you can help out by providing the necessary translations in [custom_components/ans/translations/](./custom_components/ans/translations/) and open a pull request with the changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftxxa%2Fhass-ans","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftxxa%2Fhass-ans","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftxxa%2Fhass-ans/lists"}