Aller au contenu principal

Intégration domotique Apprise, gratuite et open source

Intégration Apprise pour Gladys Assistant

Les messages de Gladys et des scènes vers plus de 100 services via votre API Apprise.

Voir sur GitHubToutes les intégrations

Envoyez les messages de Gladys vers Discord, Telegram, Matrix, Slack, ntfy, Pushover, l'e-mail, les SMS et plus de 100 autres services via votre propre API Apprise : les messages de vos scènes, les réponses de Gladys et ses messages système, ainsi que des notifications avec titre et type depuis vos scènes. Gladys parle à l'API Apprise sur votre réseau local ; Apprise joint ensuite chaque service.

Testée contre une vraie API Apprise 2.0.1 (image caronc/apprise), avec configurations enregistrées, tags et pièces jointes, mais pas dans une vraie installation de Gladys. Si quelque chose ne marche pas comme décrit, dites-le sur le forum Gladys ou dans les issues.

Ce qu'il vous faut​

  • Gladys Assistant 5.1.0 ou plus récent.
  • Une API Apprise que Gladys peut joindre sur votre réseau, par exemple l'image Docker caronc/apprise (port 8000).
  • Les services à prévenir, écrits sous forme d'URL Apprise : tgram://jeton_du_bot/chat_id pour Telegram, discord://webhook_id/webhook_token, mailto://utilisateur:[email protected], ntfy://sujet… La liste des services et la syntaxe de leurs URL sont sur appriseit.com.

Deux façons de dire à Gladys où envoyer :

  1. Une configuration enregistrée (conseillé) : dans la page web de l'API Apprise, créez une configuration sous une clé (par exemple apprise) et donnez à chaque URL un ou plusieurs tags : alice, bob, famille, ops… Gladys ne connaît alors que la clé et les tags, jamais vos mots de passe.
  2. Des URL Apprise collées dans Gladys : envoyées avec chaque notification. Plus simple, mais les URL (avec leurs mots de passe) sont stockées dans Gladys, masquées.

Mise en place​

Installez l'intégration depuis Intégrations → Installer depuis GitHub avec l'adresse https://github.com/guim31/gladys-apprise, puis remplissez son écran de configuration :

  • Adresse de l'API Apprise : l'adresse par laquelle vous ouvrez l'API Apprise, port compris, par exemple http://192.168.1.10:8000. Une API servie sous un chemin derrière un reverse proxy (https://example.org/apprise) fonctionne aussi.
  • Clé de la configuration enregistrée : apprise par défaut.
  • Tags partagés : les services joints par l'action de scène et le test. famille, ops joint les services marqués famille ou ops ; famille ops (une espace) ceux marqués famille et ops ; all tous les services. Laissé vide : seulement les services sans aucun tag.
  • URL Apprise partagées (au lieu d'une configuration) : facultatif. Si elles sont données, l'action de scène et le test les utilisent et ignorent la clé et les tags.
  • Type de notification par défaut : Information, Succès, Avertissement ou Échec. Apprise le transmet aux services qui le connaissent (couleur, icône).
  • Mettre en forme les messages en Markdown : activé par défaut. Gladys écrit gras, listes et liens en Markdown ; Apprise les convertit pour chaque service.
  • Derrière un reverse proxy (facultatif) : l'API Apprise n'a pas d'identification propre. Si vous la protégez par un reverse proxy, donnez l'utilisateur et le mot de passe de son authentification basique, ou un en-tête supplémentaire comme X-Api-Key: ….
  • Accepter un certificat auto-signé : seulement pour une adresse en https:// dont vous avez créé le certificat vous-même.
  • Langue des textes de l'intégration : français par défaut.

Ensuite, chaque personne qui veut recevoir les messages que Gladys lui envoie ouvre Mon compte (dans la page de l'intégration) et remplit :

  • Vos tags : ses tags dans la configuration enregistrée, par exemple alice ;
  • ou Vos URL Apprise (au lieu des tags) : ses propres services, masqués.

Laisser les deux vides veut dire « ne m'envoie rien ».

Enfin, utilisez Envoyer une notification de test (ou le bouton du widget) : elle vérifie l'API, dit combien de services et quels tags contient la configuration, et envoie une notification de test à la destination partagée.

Ce que Gladys envoie​

  • Les messages à une personne : une scène « Envoyer un message », les réponses de Gladys, ses messages système. Ils partent vers les tags ou les URL du Mon compte de cette personne, avec le type par défaut, en Markdown.
  • Les images de caméra (action de scène « Envoyer une image de caméra ») : envoyées en pièce jointe aux services qui en acceptent (Telegram, Discord, e-mail…). Si l'API Apprise refuse les pièces jointes (APPRISE_ATTACH_SIZE=0), le texte part seul avec une ligne qui le dit.
  • Les notifications de scène : l'action décrite plus bas.

Tableau de bord​

Le widget Apprise montre si l'API répond, combien de notifications sont parties aujourd'hui et combien ont échoué (avec la raison du dernier échec), les dernières notifications envoyées par les scènes avec leur type, et un bouton Envoyer un test. Les messages que Gladys envoie à une personne sont comptés mais jamais affichés : le tableau de bord est commun à la maison.

Scènes​

Déclencheurs​

  • API Apprise hors ligne : l'API ne répond plus (deux vérifications à 30 secondes d'écart). Variable : l'erreur.
  • API Apprise de retour : l'API répond de nouveau après avoir été hors ligne.
  • Notification Apprise non envoyée : un message n'a pas pu partir. Filtres : la raison (Apprise injoignable, configuration à vérifier, un service a échoué, notification refusée) et l'expéditeur (un message de Gladys, l'action de scène Apprise). Au plus une fois par raison toutes les 15 minutes : une scène qui y répond par une autre notification ne boucle pas. Variables : raison, expéditeur, erreur.

Actions​

Envoyer une notification Apprise :

  • Titre : facultatif.
  • Message : obligatoire ; les variables de scène fonctionnent.
  • Type : Par défaut de l'intégration, Information, Succès, Avertissement ou Échec.
  • Tags : facultatif ; remplace les tags partagés pour cette notification (configuration enregistrée seulement), par exemple ops.

Sorties : Notification envoyée (oui / non) et Erreur, pour continuer la scène autrement quand rien n'est parti.

Idées de scènes​

  • La machine à laver a fini : « Envoyer une notification Apprise » vers famille, type Succès.
  • Une fuite d'eau : type Échec, tags famille, ops, pour joindre à la fois la conversation familiale et l'e-mail de la personne d'astreinte.
  • Notification Apprise non envoyée → passer une lampe en rouge, ou envoyer le message par une autre intégration.

Dépannage​

  • « aucune API Apprise à cette adresse » : l'adresse ne mène pas à l'API Apprise (mauvais port, ou chemin manquant derrière le reverse proxy).
  • « aucune configuration enregistrée sous cette clé dans Apprise » : vérifiez la clé dans la page web de l'API Apprise.
  • « aucun service de la configuration n'a ces tags » : les tags de Mon compte ou les tags partagés ne correspondent à aucune URL. Sans tag, seules les URL sans tag sont jointes ; all joint tous les services.
  • « un service ne l'a pas reçue » : Apprise a joint l'API du service, qui a refusé ou échoué (jeton faux, webhook expiré…). Les logs de l'API Apprise nomment le service. Quand plusieurs services sont prévenus, les autres l'ont bien reçue.
  • « accès refusé » : le reverse proxy a refusé l'utilisateur, le mot de passe ou l'en-tête.
  • Logs détaillés : définissez la variable d'environnement LOG_LEVEL=debug. Les logs ne montrent jamais une URL Apprise, un mot de passe ni la valeur d'un en-tête.

Limites​

  • Envoi seulement : Apprise ne rapporte aucun message vers Gladys.
  • Gladys attend 5 secondes l'envoi d'un message. Si l'API Apprise ne répond pas dans les 4 secondes après avoir reçu toute la requête, le message compte comme envoyé : Apprise continue de le livrer, son résultat n'est pas connu.
  • La livraison est aussi fiable que chaque service : Apprise signale un échec, il ne réessaie pas plus tard.
  • Le type est une indication : les services sans couleur ni icône l'ignorent.
  • La notification de test part vers la destination partagée seulement, pas vers le Mon compte de chacun.
  • Sans lien avec Apprise ni son auteur.

Paramètres de configuration​

Voici les paramètres demandés par Apprise dans son écran de configuration dans Gladys.

ParamètreTypeObligatoireDescription
Connecter votre API ApprisesectionNonApprise envoie vers Discord, Telegram, Matrix, l'e-mail, les SMS et plus de 100 autres services. Faites tourner l'API Apprise (caronc/apprise), puis enregistrez-y une configuration (sa page web, une clé comme apprise) avec un tag par personne, ou collez des URL Apprise ci-dessous.
Adresse de l'API ApprisestringOuiL'adresse par laquelle vous ouvrez l'API Apprise, port compris.
Clé de la configuration enregistréestringNonLa configuration de l'API Apprise qui contient vos services. Ignorée si des URL Apprise sont données plus bas.
Tags partagésstringNonServices joints par l'action de scène et le test. « a, b » : a ou b ; « a b » : a et b ; all : tous. Vide : les services sans tag.
URL Apprise partagées (au lieu d'une configuration)secretNonUne par ligne ou séparées par des virgules, ex. tgram://jeton/chat_id. Elles contiennent des mots de passe : masquées, jamais journalisées.
Type de notification par défautselectNonApprise le transmet aux services qui le connaissent (couleur, icône).
Mettre en forme les messages en MarkdownbooleanNonGladys écrit gras, listes et liens en Markdown : Apprise les convertit pour chaque service.
Derrière un reverse proxy (facultatif)sectionNonL'API Apprise n'a pas d'identification propre. Si vous la protégez par un reverse proxy, donnez ses identifiants ici.
Utilisateur (authentification basique)stringNon
Mot de passe (authentification basique)secretNon
En-tête supplémentairesecretNonEnvoyé avec chaque requête, sous la forme Nom: valeur.
Accepter un certificat auto-signébooleanNonSeulement pour une adresse en https:// dont vous avez créé le certificat vous-même.
Langue des textes de l'intégrationselectNonPour les mentions ajoutées aux messages et les erreurs de l'action de scène.

Comment installer Apprise dans Gladys​

  1. Dans Gladys, ouvrez Intégrations : Apprise apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
  2. Cliquez sur Installer. Gladys télécharge l'image Docker (ghcr.io/guim31/gladys-apprise:1.0.0), la démarre dans un bac à sable isolé du cœur, et génère l'interface de l'intégration (appareils, découverte et configuration).
  3. Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
  4. Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/guim31/gladys-apprise.

Apprise nécessite Gladys >=5.1.0. Le catalogue dans Gladys se rafraîchit toutes les heures : une nouvelle version est donc disponible au plus tard une heure après sa sortie.

Vous n'utilisez pas encore Gladys ? C'est gratuit et open source : suivez le guide d'installation pour démarrer.

À propos des intégrations externes​

Apprise est une intégration externe : une intégration communautaire empaquetée dans un conteneur Docker et publiée sur GitHub, que Gladys installe en un clic et exécute dans un bac à sable isolé de son cœur. Elle est publiée et maintenue par guim31, et non par l'équipe cœur de Gladys.

Inscrivez-vous à la newsletter Gladys Assistant

Quelques emails par mois sur les nouveautés et l'actualité du projet. Envoyés par Pierre-Gilles Leymarie, le fondateur du projet. Désinscription possible à tout moment 🙂
Dernière mise à jour le