Zum Hauptinhalt springen

Twilio Smart-Home-Integration, kostenlos und Open Source

Twilio-Integration für Gladys Assistant

SMS und Sprachanrufe aus deinen Gladys-Szenen über dein Twilio-Konto, mit Kostenschutz.

Auf GitHub ansehenAlle Integrationen

Sende SMS und tätige Sprachanrufe aus deinen Gladys-Szenen über dein eigenes Twilio-Konto: eine SMS an die Familie, wenn der Wassermelder auslöst, ein Anruf, der den Alarm laut vorliest, wenn niemand aufs Handy schaut, ein Anruf beim Nachbarn, wenn ein älterer Angehöriger nicht abnimmt. Nützlich, wo eine App-Benachrichtigung nicht reicht oder kein mobiles Internet da ist.

Diese Integration ist nicht mit Twilio verbunden. Twilio berechnet jede SMS und jeden Anruf deinem Konto: Ein Kostenschutz begrenzt, was Gladys pro Stunde und pro Tag senden darf.

Ohne die Hardware entwickelt: Rückmeldungen willkommen (Developed without the hardware: feedback welcome). Diese Integration wurde nach der dokumentierten Twilio-API geschrieben, ohne echtes Twilio-Konto. Wenn etwas nicht wie beschrieben funktioniert, sag es im Gladys-Forum oder in den Issues.

Was du brauchst​

  • Gladys Assistant 5.1.0 oder neuer.
  • Ein Twilio-Konto mit Guthaben und eine Twilio-Telefonnummer, die SMS senden und Anrufe in die gewünschten Länder tätigen kann. Ein Testkonto funktioniert, mit seinen Grenzen: Es erreicht nur die in Twilio bestätigten Nummern, und seine Nachrichten beginnen mit einem Twilio-Hinweis.
  • Die Account SID (auf der Startseite der Twilio-Konsole, AC…).
  • Am besten einen API-Schlüssel: in der Twilio-Konsole Account → API keys & tokens → Create API key, Typ Standard. Notiere seine SID (SK…) und sein Secret, das nur einmal angezeigt wird. Ohne API-Schlüssel funktioniert auch das Auth Token des Kontos, es gibt aber vollen Zugriff auf das Konto.
  • In der Twilio-Konsole müssen die geografischen Berechtigungen für SMS und Sprache die Länder deiner Empfänger erlauben.

Konfiguration​

  1. Installiere die Integration aus dem Gladys-Katalog.
  2. Trag unter Konfiguration die Account SID, die SID des API-Schlüssels und das Secret des API-Schlüssels (oder das Auth Token) ein, und den Absender: deine Twilio-Nummer im internationalen Format, z. B. +4915112345678.
  3. Standardempfänger: die Nummern, die gelten, wenn eine Aktion keine nennt, durch Kommas getrennt, die wichtigste zuerst. Immer im internationalen Format (+ und Ländervorwahl): 0151 12345678 wird abgelehnt, weil das Land nicht erraten werden kann.
  4. Stell den Kostenschutz ein (siehe unten), die Stimme und die Klingeldauer der Anrufe und die Sprache (standardmäßig Französisch).
  5. Speichere und klick auf Verbindung testen: Die Meldung unter dem Knopf nennt das Konto, seinen Typ, sein Guthaben, ob der Absender zum Konto gehört, und den heutigen Verbrauch.
  6. Klick auf Test-SMS senden (an die Standardempfänger oder an die eingegebene Nummer), um den ganzen Weg zu prüfen.
  7. Öffne den Reiter Entdecken und füge das Gerät Twilio-Konto hinzu.

Der Absender kann auch die SID eines Messaging Service (MG…) oder ein alphanumerischer Absendername sein (Gladys, höchstens 11 Zeichen, wo das Zielland es erlaubt). Beides gilt nur für SMS: Ein Anruf braucht immer eine Twilio-Telefonnummer.

Kostenschutz​

Vier Grenzen: Höchstens SMS pro Stunde, Höchstens SMS pro Tag, Höchstens Anrufe pro Stunde, Höchstens Anrufe pro Tag (standardmäßig 10, 30, 5 und 10). Die Stunde ist gleitend, der Tag ist der Kalendertag in der Zeitzone von Gladys. Jeder Empfänger zählt als eine SMS. Über einer Grenze geht nichts mehr raus, bis das Zeitfenster wieder frei ist: Die ersten Empfänger einer Liste kommen zuerst dran, die anderen werden zurückgehalten. Eine Grenze von 0 sperrt diese Art des Sendens. Die Zähler liegen unter /data und überstehen einen Neustart. Nur von Twilio angenommene Sendungen zählen: Eine abgelehnte Anfrage wird nicht berechnet.

Das Gerät „Twilio-Konto“​

FunktionWas sie zeigt
GuthabenDas Guthaben des Kontos in seiner Währung, alle 15 Minuten gelesen.
Heute gesendete SMSVon Twilio seit Mitternacht angenommene SMS.
Heutige AnrufeVon Twilio seit Mitternacht angenommene Anrufe.
Letzter FehlerDatum, SMS oder Anruf, maskierte Nummer und Grund des letzten Fehlers, oder Kein Fehler.

Euro, Dollar und Pfund haben ihre Einheit; eine andere Währung zeigt nur den Betrag. Das Guthaben erscheint erst, wenn Twilio es lesen lässt: Ein eingeschränkter API-Schlüssel sieht es vielleicht nicht, was das Senden nicht verhindert.

Dashboard-Widget​

Das Widget Twilio zeigt das Guthaben, die SMS und Anrufe des Tages gegenüber den Tageslimits (orange, sobald erreicht), den Zustand des Kontos und den letzten Fehler, mit einem Link zur Twilio-Konsole zum Aufladen. Es sendet selbst nichts.

Szenen​

Aktionen​

SMS senden: eine SMS an jeden Empfänger (höchstens 10). Empfänger: Nummern durch Kommas getrennt, leer für die Standardempfänger. Nachricht: bis zu 1600 Zeichen, mit den Variablen der Szene (tippe {{, um eine einzufügen). Ergebnisse für die nächsten Schritte: Gesendete SMS, Vom Kostenschutz zurückgehalten, Von Twilio abgelehnt.

Anruf tätigen: ruft eine Nummer an (leer: der erste Standardempfänger) und liest die Vorgelesene Nachricht (bis zu 1000 Zeichen) mit einer Sprachausgabe vor. Sprache (Englisch, Französisch, Deutsch oder Spanisch) und Stimme (weiblich oder männlich) sind standardmäßig die der Konfiguration; die Nachricht wird 1 bis 3 Mal vorgelesen. Mit Auf die Antwort warten (standardmäßig an) wartet die Szene, bis feststeht, ob abgenommen wurde, höchstens die Klingeldauer plus 20 Sekunden. Ergebnisse: Abgenommen (ja oder nein), Ergebnis des Anrufs und SID des Anrufs. Das Ergebnis ist eines von:

  • answered: jemand (oder eine Mailbox) hat abgenommen;
  • no-answer, busy, failed, canceled: der Anruf kam nicht durch (keine Antwort, besetzt, fehlgeschlagen, abgebrochen);
  • refused: Twilio hat den Anruf abgelehnt (siehe Letzter Fehler);
  • blocked: vom Kostenschutz zurückgehalten;
  • pending: noch nicht bekannt (nicht abgewartet oder klingelt bei Fristende noch).

Ein Fehler auf Twilios Seite hält die Szene nie an: Prüfe die Ergebnisse mit der Bedingung Nur fortsetzen, wenn. Nur eine Aktion, die gar nicht laufen kann, schlägt fehl (keine Konfiguration, kein Empfänger, leere Nachricht, eine Nummer nicht im internationalen Format).

Auslöser​

SMS oder Anruf fehlgeschlagen: Eine SMS oder ein Anruf hat den Empfänger nicht erreicht. Filter: SMS oder Anruf, Ergebnis (von Twilio abgelehnt, fehlgeschlagen, SMS nicht zugestellt, keine Antwort, Leitung besetzt, abgebrochen), Empfänger. Variablen: SMS oder Anruf (sms oder call), Empfänger, Ergebnis, Grund (in der eingestellten Sprache), Twilio-Fehlercode. Twilio bestätigt die Zustellung im Nachhinein: Eine SMS wird nach 1, 5 und 20 Minuten nachgelesen, ein Anruf nach seiner Klingeldauer.

Limit des Kostenschutzes erreicht: SMS oder Anrufe wurden von einer Grenze zurückgehalten. Filter: SMS oder Anruf, Limit (pro Stunde oder pro Tag). Variablen: die Art, das Limit (hour oder day), sein Wert und die Zahl der zurückgehaltenen. Einmal pro Vorfall ausgelöst, nicht bei jedem Versuch: So kann er dich über einen anderen Kanal warnen, ohne ihn zu fluten.

Ideen für Szenen​

  • Wasserschaden: beim Wassermelder SMS senden „Wasser im Keller!“ an die Familie, dann Anruf tätigen beim ersten Standardempfänger.
  • Niemand nimmt ab: Anruf tätigen bei einem Angehörigen mit Auf die Antwort warten, dann Nur fortsetzen, wenn Abgenommen falsch ist, dann Anruf tätigen beim Nachbarn.
  • Etwas läuft in einer Schleife: bei Limit des Kostenschutzes erreicht eine Nachricht über die Gladys-App oder einen anderen Kanal senden, um die Szene zu finden, die so viel sendet.

Kosten und Grenzen von Twilio​

  • Twilio berechnet jede SMS pro Segment: 160 Zeichen, oder 70, sobald der Text ein Zeichen außerhalb des GSM-Alphabets enthält (ê, ç, œ, ein Emoji). Ein Text mit 1600 Zeichen kann 23 SMS ergeben. Anrufe werden pro angefangene Minute berechnet; ein Anruf wird nach 3 Minuten beendet.
  • Die Stimmen sind Standard-Stimmen von Amazon Polly, die Twilio bereitstellt; siehe die Twilio-Preise für Sprachausgabe.
  • Anfragen an api.twilio.com: das Konto und sein Guthaben alle 15 Minuten (zwei Lesezugriffe), eine Anfrage pro SMS oder Anruf, dann ein paar Lesezugriffe, um das Ergebnis zu verfolgen (alle 3 Sekunden, solange auf einen Anruf gewartet wird). Weit unter den Grenzen der Twilio-API; eine Antwort 429 wird als „zu viele Anfragen“ gemeldet.
  • Twilio tätigt höchstens etwa einen Anruf pro Sekunde und Konto und reiht die SMS im Takt des Absenders ein: Eine Liste mit 10 Empfängern dauert ein paar Sekunden.
  • Die Nutzungsrichtlinie von Twilio und die Länderrichtlinien gelten: Schreib nur Leuten, die zugestimmt haben; ein Empfänger, der mit STOP geantwortet hat, wird von Twilio blockiert.

Fehlerbehebung​

  • „Zugangsdaten von Twilio abgelehnt“: Prüf die Account SID und das Secret des API-Schlüssels (oder das Auth Token). Ein API-Schlüssel muss zum selben Konto gehören.
  • „Testkonto: Bestätige diese Nummer zuerst in Twilio“: Füge den Empfänger zu den bestätigten Nummern der Twilio-Konsole hinzu oder stell das Konto auf kostenpflichtig um.
  • „Land in den geografischen Berechtigungen von Twilio nicht erlaubt“: Aktiviere das Land in der Twilio-Konsole, für SMS und für Sprache.
  • „der Absender ist keine Nummer deines Twilio-Kontos“: Kopier die Nummer aus Phone Numbers → Active numbers, im internationalen Format.
  • „nicht zugestellt (Twilio 30003)“ und andere Codes 30xxx: Der Netzbetreiber konnte die SMS nicht zustellen (Handy aus, als Spam gefiltert, Festnetz). Der Code wird unter https://www.twilio.com/docs/api/errors/<code> erklärt.
  • Nichts geht raus und das Widget zeigt einen Zähler in Orange: Der Kostenschutz greift; erhöhe die Grenze oder warte, bis das Zeitfenster frei ist.
  • Ausführliche Protokolle: Setz LOG_LEVEL=debug für die Integration. Nummern werden in den Protokollen immer maskiert, Secrets nie geschrieben.

Grenzen​

  • Keine eingehenden SMS. Twilio stellt eingehende Nachrichten zu, indem es eine öffentliche URL aufruft; Gladys ist nicht aus dem Internet erreichbar, und das Webhook-Relay von Gladys Plus gibt den Header X-Twilio-Signature nicht weiter, sodass der Absender einer Nachricht nicht geprüft werden könnte. Eingehende SMS werden daher nicht unterstützt.
  • Eine Mailbox, die abnimmt, zählt als answered: Stell eine kürzere Klingeldauer ein, um vorher aufzulegen.
  • Keine MMS (Bilder) und kein WhatsApp: nur SMS und Sprache.
  • Die Namen der Funktionen werden beim Hinzufügen des Geräts festgelegt, in der damals konfigurierten Sprache.
  • Ohne Twilio-Konto entwickelt: Die API-Antworten stammen aus der Twilio-Dokumentation, nicht von einem echten Konto.

Konfigurationseinstellungen​

Diese Einstellungen fragt Twilio in seinem Konfigurationsbildschirm in Gladys ab.

EinstellungTypPflichtfeldBeschreibung
Dein Twilio-KontosectionNeinTwilio berechnet jede SMS und jeden Anruf deinem Konto: Stell unten den Kostenschutz ein. Die Account SID steht auf der Startseite der Twilio-Konsole; ein API-Schlüssel ist sicherer als das Auth Token.
Account SIDstringJaBeginnt mit AC, dann 32 Zeichen.
SID des API-Schlüssels (empfohlen)stringNeinEin Standard-API-Schlüssel, beginnt mit SK. Leer lassen, um das Auth Token zu verwenden.
Secret des API-SchlüsselssecretNeinWird von Twilio nur einmal beim Erstellen des Schlüssels angezeigt.
Auth TokensecretNeinNur ohne API-Schlüssel. Es gibt vollen Zugriff auf das Konto.
AbsenderstringJaDeine Twilio-Nummer im internationalen Format. Ein Absendername oder ein Messaging Service (MG…) gilt nur für SMS.
StandardempfängerstringNeinInternationale Nummern, durch Kommas getrennt, die wichtigste zuerst. Gelten, wenn eine Aktion keine nennt.
KostenschutzsectionNeinÜber diesen Grenzen wird nichts gesendet, bis das Zeitfenster wieder frei ist: Eine Szene in einer Schleife kann dein Konto nicht leeren. Jeder Empfänger zählt als eine SMS. 0 sperrt.
Höchstens SMS pro StundenumberNein
Höchstens SMS pro TagnumberNein
Höchstens Anrufe pro StundenumberNein
Höchstens Anrufe pro TagnumberNein
Anrufe und TextesectionNeinEin Anruf liest die Nachricht mit einer Sprachausgabe vor, in der Sprache der Aktion oder der unten gewählten.
StimmeselectNein
KlingeldauerselectNeinFrüher auflegen vermeidet die Mailbox, die als Antwort zählt.
SpracheselectNeinDer Anrufe, der Test-SMS, der Gerätenamen und der Fehlertexte.

So installierst du Twilio in Gladys​

  1. Öffne in Gladys Integrationen: Twilio erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
  2. Klicke auf Installieren. Gladys lädt das Docker-Image (ghcr.io/guim31/gladys-twilio:1.0.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration).
  3. Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
  4. Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/guim31/gladys-twilio.

Twilio benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.

Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.

Über externe Integrationen​

Twilio ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von guim31 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.

Abonniere den Newsletter von Gladys Assistant

Ein paar E-Mails im Monat zu neuen Releases und Neuigkeiten aus dem Projekt. Verschickt von Pierre-Gilles Leymarie, dem Gründer des Projekts. Jederzeit abbestellbar 🙂
Zuletzt aktualisiert am