WhatsApp Smart-Home-Integration, kostenlos und Open Source
Chatten Sie mit Gladys auf WhatsApp über die offizielle WhatsApp Business Cloud API.
Veröffentlicht von William-De71
- Messaging
- Version 0.1.0
- Erfordert Gladys >=5.1.0
- ★ 0
Überblick
Chatten Sie mit Gladys auf WhatsApp, über die offizielle WhatsApp Business Cloud API von Meta. Jeder Gladys-Benutzer verknüpft seine WhatsApp-Nummer; seine Nachrichten erreichen Gladys, die ihm auf WhatsApp antwortet und ihm dort ihre Benachrichtigungen sendet. Szenen können auf empfangene Nachrichten reagieren (Schaltflächen von Vorlagen, Standorte …) und genehmigte Nachrichtenvorlagen senden.
Die Integration nutzt die Cloud von Meta (graph.facebook.com): Die mit Gladys ausgetauschten Texte verlassen Ihr lokales Netzwerk. Zum Empfangen von Nachrichten ist Gladys Plus nötig, das Meta eine öffentliche HTTPS-Adresse bereitstellt; ohne Gladys Plus kann Gladys nur senden.
Voraussetzungen
- Gladys Assistant 5.1.0 oder neuer.
- Eine Meta-App vom Typ Business mit dem Produkt WhatsApp und eine geschäftliche Telefonnummer. Die von Meta bereitgestellte Testnummer funktioniert auch, erreicht aber nur die 5 unter WhatsApp → API-Einrichtung registrierten Nummern.
- Ein Systembenutzer (Unternehmenseinstellungen → Benutzer → Systembenutzer), dem die App und das WhatsApp-Konto zugewiesen sind, mit einem Token ohne Ablauf und den Berechtigungen
whatsapp_business_messagingundwhatsapp_business_management. Das temporäre Token der API-Einrichtung läuft nach 24 Stunden ab. - Gladys Plus, um Nachrichten zu empfangen.
- Meta rechnet die Nachrichten eines Unternehmens nach seiner Preisliste ab (insbesondere Vorlagen außerhalb des 24-Stunden-Fensters).
Konfiguration
| Feld | Was einzugeben ist |
|---|---|
| Telefonnummer-ID | Die unter WhatsApp → API-Einrichtung angezeigte ID (nicht die Nummer) |
| Zugriffstoken | Das dauerhafte Token des Systembenutzers |
| ID des WhatsApp-Business-Kontos | Optional: Damit registriert die Integration ihren Webhook bei Meta und listet Ihre Vorlagen |
| Verifizierungstoken | Leer lassen: Die Integration erzeugt es; bei Meta einfügen |
| Webhook registrieren | Standardmäßig an: Der Webhook des Kontos folgt der Gladys-Plus-URL |
| Ersatzvorlage | Name einer genehmigten Vorlage mit einer Variablen im Text, z. B. gladys_notification |
| Sprache der Vorlage | Ihr Sprachcode wie im WhatsApp Manager: en_US, fr, de, es … |
| Empfangene Nachrichten als gelesen markieren | Blaue Häkchen für den Absender |
| Sprache der Antworten | Sprache der Antworten, bevor eine Nummer verknüpft ist |
Nachrichten empfangen: Speichern Sie im Block Gladys-Plus-Webhooks Ihren Open-API-Schlüssel (Gladys Plus → Einstellungen → Open API). Danach erscheint die Webhook-URL. Öffnen Sie in der Meta-App WhatsApp → Konfiguration, fügen Sie diese URL als Callback-URL und das Verifizierungstoken der Integration als Verifizierungstoken ein und abonnieren Sie das Feld messages. Ist die ID des WhatsApp-Business-Kontos eingetragen, richtet die Integration den Webhook des Kontos außerdem selbst auf diese URL aus, erneut bei jeder Änderung der URL (die Schaltfläche Webhook registrieren tut es auf Anfrage).
Das 24-Stunden-Fenster: WhatsApp erlaubt einem Unternehmen freien Text nur innerhalb von 24 Stunden nach der letzten Nachricht des Nutzers. Legen Sie im WhatsApp Manager eine Vorlage an (Kategorie Utility, eine Variable im Text, z. B. Gladys: {{1}}), warten Sie auf die Genehmigung und geben Sie ihren Namen ein: Außerhalb des Fensters sendet Gladys ihre Nachrichten darüber. Ohne Vorlage lehnt Meta diese Nachrichten ab.
Verwendung
Nummer verknüpfen: Auf der Konfigurationsseite Mein Konto verknüpfen → einen Code erzeugen und diesen Code innerhalb von 15 Minuten auf WhatsApp an die geschäftliche Nummer senden. Gladys antwortet, dass Ihr Konto verknüpft ist. Schreiben Sie Gladys dann wie im Chat von Gladys.
Ohne Gladys Plus verwenden Sie die Schaltfläche Nummer ohne Gladys Plus verknüpfen: Geben Sie Ihre Nummer (internationales Format) und den Code ein. Gladys sendet Ihnen dann ihre Benachrichtigungen über die Ersatzvorlage; Ihre Nachrichten erreichen Gladys nicht.
Textnachrichten, getippte Schaltflächen und Bildunterschriften gehen an Gladys. Sprachnachrichten, Sticker und andere Medien erhalten die Antwort „Gladys liest vorerst nur Textnachrichten“. Nachrichten nicht verknüpfter Nummern werden ohne Antwort ignoriert.
Dashboard-Widget: Das Widget WhatsApp zeigt den verifizierten Namen der Nummer, ihre Qualitätsbewertung und ihr Sendelimit, die seit Mitternacht (UTC) gesendeten, empfangenen und fehlgeschlagenen Nachrichten, den Status der Nummer bei Meta, den Zustand des Empfangs, das letzte Ereignis von Meta und die Zahl der verknüpften Kontakte.
Szenen:
- Auslöser WhatsApp-Nachricht empfangen: Filter nach Nachrichtentyp, Nutzlast einer Schaltfläche, genauem Text. Variablen:
from,contact_name,user,message_type,text,payload,latitude,longitude,emoji,message_id. - Auslöser WhatsApp-Nachricht nicht zugestellt: der erste Fehler für eine Nummer, danach erst wieder, nachdem eine Nachricht durchgegangen ist (eine Szene, die Sie über WhatsApp warnt, kann keine Schleife bilden). Variablen:
to,reason,error_code,error_title,message_id. - Aktion WhatsApp-Vorlage senden: Empfänger (leer: alle verknüpften Kontakte), Name der Vorlage, Sprache, durch
|getrennte Parameter (odername=wertfür benannte Parameter). Szenenvariablen funktionieren in jedem Feld.
Beispiele: Wenn die Vorlagen-Schaltfläche mit der Nutzlast OPEN_GATE getippt wird → das Tor öffnen; wenn die Alarmanlage auslöst → die Vorlage alarm_alert an alle senden; wenn eine Nachricht wegen des Tokens nicht zugestellt wird → eine E-Mail senden.
Fehlerbehebung
- Verbindung testen zeigt Name, Qualität und Status der Nummer und ob der Empfang funktioniert.
- „Meta hat das Zugriffstoken abgelehnt“: Das Token ist abgelaufen (temporäres Token) oder wurde widerrufen. Erzeugen Sie ein dauerhaftes Token für den Systembenutzer.
- Nichts kommt in Gladys an: Prüfen Sie, ob Gladys Plus verknüpft und der Open-API-Schlüssel gespeichert ist, ob URL und Verifizierungstoken bei Meta eingefügt sind und ob das Feld messages abonniert ist. Das Widget zeigt „wartet auf Meta“ bis zum ersten Ereignis.
- Nachricht nicht zugestellt, außerhalb des Fensters (131047): Richten Sie eine genehmigte Ersatzvorlage ein.
- Nummer nicht zugelassen (131030): Fügen Sie bei der Testnummer von Meta den Empfänger unter WhatsApp → API-Einrichtung hinzu.
- Vorlage abgelehnt (132000, 132001): Prüfen Sie Name, Sprachcode und Anzahl der Parameter.
- Drücken Sie Diagnose und kopieren Sie die Zeilen, die mit „WhatsApp diagnostic“ beginnen, aus dem Tab Protokolle in ein GitHub-Issue: Token, Open-API-Schlüssel und Nummern sind entfernt oder maskiert.
Konfigurationseinstellungen
Diese Einstellungen fragt WhatsApp in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| WhatsApp-Business-Konto verbinden | section | Nein | 1. Erstellen Sie eine Meta-App vom Typ Business und fügen Sie das Produkt WhatsApp hinzu. 2. Kopieren Sie unter WhatsApp → API-Einrichtung die Telefonnummer-ID und die ID des WhatsApp-Business-Kontos. 3. Legen Sie in den Unternehmenseinstellungen einen Systembenutzer an, weisen Sie ihm die App und das WhatsApp-Konto zu und erzeugen Sie ein Token ohne Ablauf mit den Berechtigungen whatsapp_business_messaging und whatsapp_business_management. |
| Telefonnummer-ID | string | Ja | Die ID der geschäftlichen Telefonnummer unter WhatsApp → API-Einrichtung (nicht die Nummer selbst). |
| Zugriffstoken | secret | Ja | Dauerhaftes Token des Systembenutzers. Das temporäre Token der API-Einrichtung läuft nach 24 Stunden ab. Wird verschlüsselt gespeichert und nie wieder angezeigt. |
| ID des WhatsApp-Business-Kontos | string | Nein | Optional. Damit richtet die Integration den Webhook des Kontos selbst auf Gladys Plus aus, und die Diagnose listet Ihre Nachrichtenvorlagen auf. |
| Nachrichten empfangen (Gladys Plus) | section | Nein | Meta stellt die Nachrichten an eine öffentliche HTTPS-Adresse zu: Gladys Plus stellt sie bereit. Speichern Sie Ihren Open-API-Schlüssel im Block „Gladys-Plus-Webhooks“ unten, fügen Sie dann in der Meta-App (WhatsApp → Konfiguration) die dort angezeigte Webhook-URL als Callback-URL und das Verifizierungstoken unten ein und abonnieren Sie das Feld „messages“. Ohne Gladys Plus kann Gladys nur senden. |
| Verifizierungstoken | string | Nein | Wird von der Integration erzeugt, wenn es leer ist. Fügen Sie denselben Wert in der Meta-App ein (WhatsApp → Konfiguration → Verifizierungstoken). |
| Webhook automatisch bei Meta registrieren | boolean | Nein | Erfordert die ID des WhatsApp-Business-Kontos. Wird bei jeder Änderung der Gladys-Plus-URL wiederholt. |
| Außerhalb des 24-Stunden-Fensters | section | Nein | WhatsApp erlaubt einem Unternehmen freien Text nur innerhalb von 24 Stunden nach der letzten Nachricht des Nutzers. Danach kommt nur eine genehmigte Nachrichtenvorlage durch. Legen Sie eine Vorlage der Kategorie Utility mit einer einzigen Variablen im Text an, z. B. „Gladys: {{1}}“, und geben Sie ihren Namen unten ein: Gladys sendet ihre Benachrichtigungen dann darüber. |
| Ersatzvorlage | string | Nein | Name der genehmigten Vorlage (Kleinbuchstaben, Ziffern, Unterstriche). Leer: Nachrichten außerhalb des Fensters werden nicht zugestellt. |
| Sprache der Vorlage | string | Nein | Sprachcode der Vorlage wie im WhatsApp Manager: en_US, fr, de, es … |
| Empfangene Nachrichten als gelesen markieren | boolean | Nein | Der Absender sieht die blauen Häkchen, sobald Gladys die Nachricht hat. |
| Sprache der Antworten | select | Nein | Sprache der wenigen Antworten, die die Integration selbst sendet, bevor eine Nummer verknüpft ist (Verknüpfungscode angenommen oder abgelehnt). |
So installierst du WhatsApp in Gladys
- Öffne in Gladys Integrationen: WhatsApp erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/william-de71/gladys-whatsapp:0.1.0) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration). - Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
- Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/William-De71/gladys-whatsapp.
WhatsApp 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
WhatsApp 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 William-De71 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.
- Alle Integrationen durchsuchen, native und aus der Community
- Deine eigene externe Integration bauen und veröffentlichen
- Quellcode auf GitHub — Quelle dieser Dokumentation