Aller au contenu principal

Intégration domotique Twilio, gratuite et open source

Intégration Twilio pour Gladys Assistant

SMS et appels vocaux depuis vos scènes Gladys via votre compte Twilio, avec un garde-fou de coût.

Voir sur GitHubToutes les intégrations

Envoyez des SMS et passez des appels vocaux depuis vos scènes Gladys avec votre propre compte Twilio : un SMS à la famille quand le détecteur de fuite d’eau se déclenche, un appel qui lit l’alarme à voix haute quand personne ne regarde son téléphone, un appel au voisin quand un proche âgé ne répond pas. Utile là où une notification d’application ne suffit pas, ou sans Internet mobile.

Cette intégration n’est pas affiliée à Twilio. Twilio facture chaque SMS et chaque appel sur votre compte : un garde-fou de coût plafonne ce que Gladys peut envoyer par heure et par jour.

Développée sans le matériel : vos retours sont les bienvenus (Developed without the hardware: feedback welcome). Cette intégration a été écrite d’après l’API documentée de Twilio, sans vrai compte Twilio. 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.
  • Un compte Twilio avec du crédit, et un numéro Twilio capable d’envoyer des SMS et de passer des appels vers les pays voulus. Un compte d’essai marche, avec ses limites : il ne joint que les numéros vérifiés dans Twilio, et ses messages commencent par une mention Twilio.
  • L’Account SID (sur l’accueil de la console Twilio, AC…).
  • De préférence une clé d’API : dans la console Twilio, Account → API keys & tokens → Create API key, type Standard. Notez son SID (SK…) et son secret, affiché une seule fois. Sans clé d’API, l’Auth Token du compte marche aussi, mais il donne un accès complet au compte.
  • Dans la console Twilio, les permissions géographiques des SMS et de la voix doivent autoriser les pays de vos destinataires.

Configuration​

  1. Installez l’intégration depuis le catalogue de Gladys.
  2. Dans Configuration, renseignez l’Account SID, le SID de la clé d’API et le Secret de la clé d’API (ou l’Auth Token), et l’Expéditeur : votre numéro Twilio au format international, ex. +33612345678.
  3. Destinataires par défaut : les numéros utilisés quand une action n’en donne pas, séparés par des virgules, le plus important en premier. Toujours au format international (+ et indicatif du pays) : 06 12 34 56 78 est refusé, car le pays ne peut pas être deviné.
  4. Réglez le garde-fou (voir plus bas), la Voix et la Durée de sonnerie des appels, et la Langue (français par défaut).
  5. Enregistrez, puis cliquez sur Tester la connexion : le message sous le bouton donne le compte, son type, son solde, si l’expéditeur appartient au compte, et la consommation du jour.
  6. Cliquez sur Envoyer un SMS de test (aux destinataires par défaut, ou au numéro saisi) pour vérifier toute la chaîne.
  7. Ouvrez l’onglet Découverte et ajoutez l’appareil Compte Twilio.

L’expéditeur peut aussi être le SID d’un Messaging Service (MG…) ou un nom d’expéditeur alphanumérique (Gladys, 11 caractères au plus, là où le pays de destination l’accepte). Les deux ne servent qu’aux SMS : un appel exige toujours un numéro Twilio.

Garde-fou de coût​

Quatre plafonds : SMS par heure, au plus, SMS par jour, au plus, Appels par heure, au plus, Appels par jour, au plus (10, 30, 5 et 10 par défaut). L’heure est glissante, le jour est le jour calendaire dans le fuseau de Gladys. Chaque destinataire compte pour un SMS. Au-delà d’un plafond, plus rien ne part jusqu’à ce que la fenêtre se libère : les premiers destinataires d’une liste passent d’abord, les autres sont retenus. Un plafond à 0 bloque ce type d’envoi. Les compteurs sont gardés dans /data et survivent à un redémarrage. Seuls les envois acceptés par Twilio comptent : une demande refusée n’est pas facturée.

L’appareil « Compte Twilio »​

FonctionnalitéCe qu’elle montre
SoldeLe solde du compte, dans sa devise, lu toutes les 15 minutes.
SMS envoyés aujourd’huiLes SMS acceptés par Twilio depuis minuit.
Appels passés aujourd’huiLes appels acceptés par Twilio depuis minuit.
Dernier échecDate, SMS ou appel, numéro masqué et raison du dernier échec, ou Aucun échec.

Les euros, dollars et livres ont leur unité ; une autre devise affiche le montant seul. Le solde n’apparaît qu’une fois que Twilio l’a laissé lire : une clé d’API restreinte peut ne pas le voir, ce qui n’empêche pas d’envoyer.

Widget du tableau de bord​

Le widget Twilio affiche le solde, les SMS et appels du jour face aux plafonds journaliers (en orange une fois atteints), l’état du compte et le dernier échec, avec un lien vers la console Twilio pour recharger le solde. Il n’envoie rien lui-même.

Scènes​

Actions​

Envoyer un SMS : un SMS à chaque destinataire (10 au plus). Destinataires : numéros séparés par des virgules, vide pour les destinataires par défaut. Message : jusqu’à 1600 caractères, avec les variables de la scène (tapez {{ pour en insérer une). Résultats pour les étapes suivantes : SMS envoyés, Retenus par le garde-fou, Refusés par Twilio.

Passer un appel : appelle un numéro (vide : le premier destinataire par défaut) et lit le Message lu (jusqu’à 1000 caractères) avec une voix de synthèse. La Langue (anglais, français, allemand ou espagnol) et la Voix (féminine ou masculine) sont par défaut celles de la configuration ; le message est lu 1 à 3 fois. Avec Attendre la réponse coché (par défaut), la scène attend de savoir si l’appel a abouti, au plus la durée de sonnerie plus 20 secondes. Résultats : Décroché (oui ou non), Résultat de l’appel et SID de l’appel. Le résultat vaut :

  • answered : quelqu’un (ou une messagerie) a décroché ;
  • no-answer, busy, failed, canceled : l’appel n’a pas abouti (pas de réponse, occupé, échec, annulé) ;
  • refused : Twilio a refusé l’appel (voir Dernier échec) ;
  • blocked : retenu par le garde-fou ;
  • pending : pas encore connu (pas attendu, ou sonne encore à l’échéance).

Un échec côté Twilio n’arrête jamais la scène : testez les résultats avec une Condition sur variables. Seule une action impossible à lancer échoue (pas de configuration, pas de destinataire, message vide, numéro hors format international).

Déclencheurs​

SMS ou appel en échec : un SMS ou un appel n’a pas atteint son destinataire. Filtres : SMS ou appel, Résultat (refusé par Twilio, échoué, SMS non distribué, pas de réponse, ligne occupée, annulé), Destinataire. Variables : SMS ou appel (sms ou call), Destinataire, Résultat, Raison (dans la langue configurée), Code d’erreur Twilio. Twilio confirme la distribution après coup : un SMS est relu après 1, 5 et 20 minutes, un appel après sa durée de sonnerie.

Plafond du garde-fou atteint : des SMS ou appels ont été retenus par un plafond. Filtres : SMS ou appel, Plafond (par heure ou par jour). Variables : le type, le plafond (hour ou day), sa valeur et le nombre de retenus. Déclenché une fois par épisode, pas à chaque tentative : il peut vous alerter par un autre canal sans l’inonder.

Idées de scènes​

  • Fuite d’eau : sur le détecteur de fuite, Envoyer un SMS « Fuite d’eau à la cave ! » à la famille, puis Passer un appel au premier destinataire par défaut.
  • Personne ne répond : Passer un appel à un proche avec Attendre la réponse, puis une Condition sur variables : Décroché est faux, puis Passer un appel au voisin.
  • Quelque chose boucle : sur Plafond du garde-fou atteint, envoyez un message par l’application Gladys ou un autre canal pour chercher quelle scène envoie autant.

Coûts et limites de Twilio​

  • Twilio facture chaque SMS par segment : 160 caractères, ou 70 dès que le texte contient un caractère hors de l’alphabet GSM (ê, ç, œ, un emoji). Un texte de 1600 caractères peut faire 23 SMS. Les appels sont facturés à la minute entamée ; un appel est coupé au bout de 3 minutes.
  • Les voix sont des voix Amazon Polly standard fournies par Twilio ; voir les tarifs Twilio de la synthèse vocale.
  • Requêtes vers api.twilio.com : le compte et son solde toutes les 15 minutes (deux lectures), une requête par SMS ou appel, puis quelques lectures pour en suivre le résultat (toutes les 3 secondes quand un appel est attendu). Très en dessous des limites de l’API Twilio ; une réponse 429 est signalée comme « trop de requêtes ».
  • Twilio passe environ un appel par seconde et par compte au plus, et met les SMS en file au rythme de l’expéditeur : une liste de 10 destinataires prend quelques secondes.
  • La politique d’usage acceptable de Twilio et ses règles par pays s’appliquent : n’écrivez qu’aux personnes d’accord ; un destinataire qui a répondu STOP est bloqué par Twilio.

Dépannage​

  • « identifiants refusés par Twilio » : vérifiez l’Account SID et le secret de la clé d’API (ou l’Auth Token). Une clé d’API doit appartenir au même compte.
  • « compte d’essai : vérifiez d’abord ce numéro dans Twilio » : ajoutez le destinataire aux numéros vérifiés de la console Twilio, ou passez le compte en payant.
  • « pays non autorisé dans les permissions géographiques Twilio » : activez le pays dans la console Twilio, pour les SMS et pour la voix.
  • « l’expéditeur n’est pas un numéro de votre compte Twilio » : copiez le numéro depuis Phone Numbers → Active numbers, au format international.
  • « non distribué (Twilio 30003) » et autres codes 30xxx : l’opérateur n’a pas pu remettre le SMS (téléphone éteint, filtré comme spam, ligne fixe). Le code est expliqué sur https://www.twilio.com/docs/api/errors/<code>.
  • Rien ne part et le widget montre un compteur en orange : le garde-fou bloque ; relevez le plafond ou attendez que la fenêtre se libère.
  • Journaux détaillés : réglez LOG_LEVEL=debug sur l’intégration. Les numéros sont toujours masqués dans les journaux, les secrets jamais écrits.

Limites​

  • Pas de SMS entrants. Twilio remet les messages entrants en appelant une URL publique ; Gladys n’est pas exposé à Internet, et le relais de webhooks de Gladys Plus ne transmet pas l’en-tête X-Twilio-Signature, si bien que l’expéditeur d’un message ne pourrait pas être authentifié. Les SMS entrants ne sont donc pas pris en charge.
  • Une messagerie vocale qui décroche compte comme answered : réglez une Durée de sonnerie plus courte pour raccrocher avant.
  • Ni MMS (images) ni WhatsApp : SMS et voix seulement.
  • Les noms des fonctionnalités sont fixés à l’ajout de l’appareil, dans la langue de la configuration à ce moment-là.
  • Développée sans compte Twilio : les réponses de l’API viennent de la documentation Twilio, pas d’un vrai compte.

Paramètres de configuration​

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

ParamètreTypeObligatoireDescription
Votre compte TwiliosectionNonTwilio facture chaque SMS et chaque appel sur votre compte : réglez le garde-fou ci-dessous. L’Account SID est sur l’accueil de la console Twilio ; une clé d’API est plus sûre que l’Auth Token.
Account SIDstringOuiCommence par AC, puis 32 caractères.
SID de la clé d’API (conseillé)stringNonUne clé d’API Standard, qui commence par SK. Vide pour utiliser l’Auth Token.
Secret de la clé d’APIsecretNonAffiché une seule fois par Twilio à la création de la clé.
Auth TokensecretNonSeulement sans clé d’API. Il donne un accès complet au compte.
ExpéditeurstringOuiVotre numéro Twilio au format international. Un nom d’expéditeur ou un Messaging Service (MG…) ne sert qu’aux SMS.
Destinataires par défautstringNonNuméros internationaux séparés par des virgules, le plus important en premier. Utilisés quand une action n’en donne pas.
Garde-fou de coûtsectionNonAu-delà de ces plafonds, rien n’est envoyé jusqu’à ce que la fenêtre se libère : une scène qui boucle ne peut pas vider votre compte. Chaque destinataire compte pour un SMS. 0 bloque.
SMS par heure, au plusnumberNon
SMS par jour, au plusnumberNon
Appels par heure, au plusnumberNon
Appels par jour, au plusnumberNon
Appels et textessectionNonUn appel lit le message avec une voix de synthèse, dans la langue choisie dans l’action ou ci-dessous.
VoixselectNon
Durée de sonnerieselectNonRaccrocher plus tôt évite la messagerie, qui compte comme une réponse.
LangueselectNonDes appels, du SMS de test, des noms de l’appareil et des textes d’échec.

Comment installer Twilio dans Gladys​

  1. Dans Gladys, ouvrez Intégrations : Twilio 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-twilio:1.0.1), 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-twilio.

Twilio 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​

Twilio 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