Intégration de Home Assistant (HASS.IO) avec Apprise

Ce guide explique comment intégrer Apprise à Home Assistant à l’aide de la plateforme de notification Apprise intégrée. Cette approche vous permet de centraliser toute la logique de notification dans un seul fichier de configuration, ou dans une source Apprise API, tout en laissant Home Assistant se concentrer sur la logique d’automatisation.

Pourquoi Utiliser Apprise avec Home Assistant

Utiliser Apprise apporte plusieurs avantages :

un seul fichier de configuration pour tous vos services de notification ;
la prise en charge de dizaines de fournisseurs, comme l’e-mail, Telegram, ntfy, Kodi, et bien d’autres ;
un routage basé sur les tags pour cibler les notifications avec souplesse ;
aucune dépendance forte à un fournisseur au niveau de vos automatisations.

Home Assistant n’a pas besoin de connaître les détails propres à chaque fournisseur. Il transmet simplement les messages à Apprise, qui se charge du reste.

1. Installation

Apprise est intégré à Home Assistant Core. Vous n’avez pas besoin d’installer un composant personnalisé ni un module complémentaire. Il est disponible immédiatement via la plateforme notify.

2. Configuration

Choisissez la méthode de configuration qui correspond le mieux à votre usage.

Cette méthode convient bien pour une configuration rapide ou lorsque vous n’avez pas besoin de cibler différents services individuellement. Le paramètre url accepte une seule URL ou une liste d’URL — toutes sont notifiées ensemble à chaque appel.

Modifiez configuration.yaml

Ajoutez une ou plusieurs URL directement dans votre fichier de configuration.

notify:
  - name: apprise_quick
    platform: apprise
    url: tgram://123456789:ABCDefghIJKLmnOPqrstUVwxyz

Pour notifier plusieurs services, fournissez-les sous forme de liste :

notify:
  - name: apprise_quick
    platform: apprise
    url:
      - tgram://123456789:ABCDefghIJKLmnOPqrstUVwxyz
      - mailtos://user:pass@smtp.gmail.com

Cette méthode est la plus adaptée pour gérer plusieurs services de notification, des groupes complexes et une logique basée sur les tags.

Apprise détecte automatiquement le type de fichier utilisé. Vous pouvez employer des fichiers YAML (structurés) ou TEXT (liste simple).

Étape A : Modifiez configuration.yaml

Pointez Home Assistant vers le fichier de configuration de votre choix.

notify:
  - name: apprise
    platform: apprise
    # Vous pouvez référencer un fichier YAML...
    config: /config/apprise.yaml

    # ...OU un fichier texte simple
    # config: /config/apprise.conf

Étape B : Créez votre fichier de configuration

Option A : YAML (Structuré)
Option B : TEXT (Simple)

Créez /config/apprise.yaml. Cette option convient le mieux aux configurations complexes.

urls:
  - tgram://123456789:ABCDefghIJKLmnOPqrstUVwxyz:
      tag: telegram
  - mailtos://user:pass@smtp.gmail.com:
      tag: mail

Vous pouvez aussi utiliser la directive include dans votre fichier local pour intégrer des configurations distantes tout en conservant des entrées locales.

# Pointer vers une instance Apprise API :
include http://apprise.host/get/my-profile-key

urls:
  # Plus des surcharges locales
  - mailtos://local-user@example.com

Créez /config/apprise.conf. Cette option convient mieux aux listes d’URL simples.

# Tag défini par préfixe
telegram=tgram://123456789:ABCDefghIJKLmnOPqrstUVwxyz

# Plusieurs tags définis par des virgules
mail,devops=mailtos://user:pass@smtp.gmail.com

Vous pouvez aussi utiliser la directive include dans votre fichier local pour intégrer des configurations distantes tout en conservant des entrées locales.

# Pointer vers une instance Apprise API :
include http://apprise.host/get/my-profile-key

# Plus des surcharges locales
mailtos://local-user@example.com

Cette méthode est idéale pour des configurations itinérantes. Si vous gérez plusieurs instances Home Assistant ou d’autres services, vous pouvez centraliser toute votre logique de notification dans une instance Apprise API auto-hébergée.

Modifiez configuration.yaml

Au lieu de référencer un fichier local, pointez directement le paramètre config vers votre point de terminaison API.

notify:
  - name: apprise_api
    platform: apprise
    # Apprise récupérera la configuration depuis cette URL
    config: https://apprise.host/get/my-profile-key

3. Utilisation dans les Automatisations

Une fois la configuration en place et Home Assistant redémarré, vous pouvez envoyer des notifications à l’aide du service notify.

Exemple : Utiliser la Méthode 1 (Inline)

Si vous avez utilisé la Méthode 1, votre service s’appelle probablement notify.apprise_quick. Vous n’avez pas besoin de fournir un champ target, car la destination est codée en dur dans votre configuration.

- alias: "[Interactive] - Sunset Notice"
  trigger:
    platform: sun
    event: sunset

  action:
    # Correspond au champ 'name' défini dans configuration.yaml
    service: notify.apprise_quick
    data:
      title: "Bonsoir"
      message: "Le soleil se couche."

Exemple : Utiliser les Méthodes 2 et 3 (Basées sur la Configuration)

Si vous avez utilisé la Méthode 2 ou la Méthode 3, vous pouvez contrôler précisément qui reçoit les notifications en utilisant le champ target, qui doit correspondre aux tags définis dans votre fichier YAML ou votre configuration API.

- alias: "[Interactive] - Sunset Notice"
  trigger:
    platform: sun
    event: sunset

  action:
    service: notify.apprise
    data:
      # Ce 'target' correspond au 'tag' de votre configuration
      target: email
      title: "Bonsoir"
      message: "Le soleil se couche."

Logique Avancée avec les Tags

Vous pouvez combiner les tags dans votre champ target afin de créer à la volée des groupes de notification puissants.

Valeur de `target`	Logique	Description
`target: devops`	Simple	Notifie tous les services tagués `devops`.
`target: [devops, alarm]`	OU	Notifie tous les services tagués `devops` OU `alarm`.
`target: "devops alarm"`	ET	Notifie uniquement les services qui possèdent LES DEUX tags.

4. Tester Votre Configuration

Avant d’intégrer Apprise dans vos automatisations, vérifiez qu’il fonctionne bien depuis la ligne de commande :

apprise -vv -t "Test" -b "Bonjour depuis la CLI" \
    tgram://YOUR_BOT_TOKEN/YOUR_CHAT_ID

Confirmez ensuite que Home Assistant peut joindre le même service en déclenchant manuellement le service notify.apprise depuis Outils de développement → Services.

5. Découvrir les Services `notify` Disponibles

Si vous souhaitez qu’Apprise appelle Home Assistant lui-même en retour, par exemple pour envoyer une notification push vers un appareil mobile enregistré dans l’application compagnon HA, vous pouvez utiliser le plugin hassio:// dans vos URL Apprise. Pour trouver le nom exact du service :

Dans Home Assistant, ouvrez Outils de développement → Services.
Filtrez sur le domaine notify. Vous verrez des entrées comme notify.mobile_app_johns_phone.
La partie située après notify. correspond au nom de service à utiliser dans l’URL Apprise :

apprise -vv -t "Alerte" -b "Test push" \
    'hassio://ha.local/YOUR_TOKEN/notify.mobile_app_johns_phone'

Consultez le plugin de service Home Assistant pour la référence complète de l’URL hassio://.

6. Débogage et Journalisation

Si vos notifications ne partent pas, vous pouvez activer la journalisation de débogage spécifiquement pour le composant Apprise dans Home Assistant. Ajoutez ceci à votre configuration.yaml :

logger:
  default: info
  logs:
    homeassistant.components.apprise: debug

Après redémarrage, consultez les journaux de Home Assistant. Vous verrez Apprise tenter de charger votre configuration et d’envoyer les messages, ce qui vous aidera à repérer les URL invalides ou les problèmes réseau.

Questions ou commentaires ?

Documentation

Vous avez repéré une faute de frappe ou une erreur ? Signalez-la ou proposez une correction .

Problèmes Techniques

Vous rencontrez un problème avec le code ? Ouvrez un ticket sur GitHub :