Intégration domotique WhatsApp, gratuite et open source
Discutez avec Gladys sur WhatsApp via l'API officielle WhatsApp Business Cloud de Meta.
Publiée par William-De71
- Messagerie
- Version 0.1.0
- Nécessite Gladys >=5.1.0
- ★ 0
Présentation
Discutez avec Gladys sur WhatsApp, via l'API officielle WhatsApp Business Cloud de Meta. Chaque utilisateur de Gladys lie son numéro WhatsApp ; ses messages arrivent à Gladys, qui lui répond sur WhatsApp et lui y envoie ses notifications. Les scènes peuvent réagir aux messages reçus (boutons de modèles, positions…) et envoyer des modèles de message approuvés.
L'intégration passe par le cloud de Meta (graph.facebook.com) : les textes échangés avec Gladys quittent votre réseau local. Recevoir des messages nécessite Gladys Plus, qui fournit à Meta une adresse HTTPS publique ; sans lui, Gladys peut seulement envoyer.
Prérequis
- Gladys Assistant 5.1.0 ou plus récent.
- Une application Meta de type Entreprise, avec le produit WhatsApp, et un numéro professionnel. Le numéro de test fourni par Meta fonctionne aussi, mais n'atteint que les 5 numéros enregistrés dans WhatsApp → Configuration de l'API.
- Un utilisateur système (Paramètres de l'entreprise → Utilisateurs → Utilisateurs système) qui dispose de l'application et du compte WhatsApp, avec un jeton sans expiration et les autorisations
whatsapp_business_messagingetwhatsapp_business_management. Le jeton temporaire de la page de configuration de l'API expire au bout de 24 heures. - Gladys Plus, pour recevoir les messages.
- Meta facture les messages d'une entreprise selon sa grille (notamment les modèles envoyés hors de la fenêtre de 24 heures).
Configuration
| Champ | Ce qu'il faut saisir |
|---|---|
| Identifiant du numéro de téléphone | L'identifiant affiché dans WhatsApp → Configuration de l'API (pas le numéro) |
| Jeton d'accès | Le jeton permanent de l'utilisateur système |
| Identifiant du compte WhatsApp Business | Facultatif : permet à l'intégration d'enregistrer son webhook chez Meta et de lister vos modèles |
| Jeton de vérification | Laissez vide : l'intégration le génère ; collez-le chez Meta |
| Enregistrer le webhook | Activé par défaut : le webhook du compte suit l'URL Gladys Plus |
| Modèle de secours | Nom d'un modèle approuvé avec une variable dans le corps, ex. gladys_notification |
| Langue du modèle | Son code de langue, comme dans WhatsApp Manager : en_US, fr, de, es… |
| Marquer les messages reçus comme lus | Coches bleues pour l'expéditeur |
| Langue des réponses | Langue des réponses envoyées avant qu'un numéro soit lié |
Recevoir les messages : dans le bloc Webhooks Gladys Plus, enregistrez votre clé Open API (Gladys Plus → Paramètres → Open API). L'URL du webhook s'affiche alors. Dans l'application Meta, ouvrez WhatsApp → Configuration, collez cette URL comme URL de rappel et le jeton de vérification de l'intégration comme Jeton de vérification, puis abonnez-vous au champ messages. Si l'identifiant du compte WhatsApp Business est renseigné, l'intégration dirige aussi elle-même le webhook du compte vers cette URL, et recommence à chaque changement d'URL (le bouton Enregistrer le webhook le fait à la demande).
La fenêtre de 24 heures : WhatsApp ne laisse une entreprise envoyer du texte libre que dans les 24 heures qui suivent le dernier message de l'utilisateur. Créez un modèle dans WhatsApp Manager (catégorie Utilitaire, une variable dans le corps, par exemple Gladys : {{1}}), attendez son approbation et indiquez son nom : hors de la fenêtre, Gladys fait passer ses messages par lui. Sans lui, ces messages sont refusés par Meta.
Utilisation
Lier votre numéro : dans l'écran de configuration, Lier mon compte → générez un code, puis envoyez ce code sur WhatsApp au numéro professionnel, dans les 15 minutes. Gladys répond que votre compte est lié. Écrivez ensuite à Gladys comme dans la discussion de Gladys.
Sans Gladys Plus, utilisez le bouton Lier un numéro sans Gladys Plus : saisissez votre numéro (format international) et le code. Gladys vous envoie alors ses notifications via le modèle de secours ; vos messages n'atteignent pas Gladys.
Les messages texte, les boutons touchés et les légendes vont à Gladys. Les notes vocales, stickers et autres médias reçoivent la réponse « Gladys ne lit que les messages texte pour le moment ». Les messages des numéros non liés sont ignorés, sans réponse.
Widget de tableau de bord : le widget WhatsApp affiche le nom vérifié du numéro, sa note de qualité et sa limite d'envoi, les messages envoyés, reçus et en échec depuis minuit (UTC), le statut du numéro chez Meta, l'état de la réception, le dernier événement de Meta et le nombre de contacts liés.
Scènes :
- Déclencheur Message WhatsApp reçu : filtres sur le type de message, la charge utile d'un bouton, un texte exact. Variables :
from,contact_name,user,message_type,text,payload,latitude,longitude,emoji,message_id. - Déclencheur Message WhatsApp non remis : le premier échec pour un numéro, puis seulement après qu'un message est passé (une scène qui vous prévient sur WhatsApp ne peut pas boucler). Variables :
to,reason,error_code,error_title,message_id. - Action Envoyer un modèle WhatsApp : destinataire (vide : tous les contacts liés), nom du modèle, langue, paramètres du corps séparés par
|(ounom=valeurpour les paramètres nommés). Les variables de scène fonctionnent dans chaque champ.
Exemples : quand le bouton de modèle de charge utile OPEN_GATE est touché → ouvrir le portail ; quand l'alarme se déclenche → envoyer le modèle alerte_alarme à tout le monde ; quand un message n'est pas remis à cause du jeton → envoyer un e-mail.
Dépannage
- Tester la connexion affiche le nom, la qualité et le statut du numéro, et si la réception fonctionne.
- « Meta a refusé le jeton d'accès » : le jeton a expiré (jeton temporaire) ou a été révoqué. Générez un jeton permanent pour l'utilisateur système.
- Rien n'arrive dans Gladys : vérifiez que Gladys Plus est lié, que la clé Open API est enregistrée, que l'URL et le jeton de vérification sont collés chez Meta et que le champ messages est abonné. Le widget affiche « en attente de Meta » jusqu'au premier événement.
- Message non remis, hors fenêtre (131047) : configurez un modèle de secours approuvé.
- Numéro non autorisé (131030) : avec le numéro de test de Meta, ajoutez le destinataire dans WhatsApp → Configuration de l'API.
- Modèle refusé (132000, 132001) : vérifiez le nom, le code de langue et le nombre de paramètres.
- Appuyez sur Diagnostic et copiez les lignes commençant par « WhatsApp diagnostic » de l'onglet Journaux dans une issue GitHub : le jeton, la clé Open API et les numéros en sont retirés ou masqués.
Paramètres de configuration
Voici les paramètres demandés par WhatsApp dans son écran de configuration dans Gladys.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| Connecter votre compte WhatsApp Business | section | Non | 1. Créez une application Meta de type Entreprise et ajoutez-lui le produit WhatsApp. 2. Dans WhatsApp → Configuration de l'API, copiez l'identifiant du numéro de téléphone et celui du compte WhatsApp Business. 3. Dans les paramètres de l'entreprise, créez un utilisateur système, donnez-lui l'application et le compte WhatsApp, puis générez un jeton sans expiration avec les autorisations whatsapp_business_messaging et whatsapp_business_management. |
| Identifiant du numéro de téléphone | string | Oui | L'identifiant du numéro professionnel dans WhatsApp → Configuration de l'API (pas le numéro lui-même). |
| Jeton d'accès | secret | Oui | Jeton permanent de l'utilisateur système. Le jeton temporaire de la page de configuration de l'API expire au bout de 24 heures. Stocké chiffré, il n'est plus jamais affiché. |
| Identifiant du compte WhatsApp Business | string | Non | Facultatif. Avec lui, l'intégration dirige elle-même le webhook du compte vers Gladys Plus, et le diagnostic liste vos modèles de message. |
| Recevoir les messages (Gladys Plus) | section | Non | Meta remet les messages à une adresse HTTPS publique : Gladys Plus la fournit. Enregistrez votre clé Open API dans le bloc « Webhooks Gladys Plus » ci-dessous, puis, dans l'application Meta (WhatsApp → Configuration), collez l'URL de webhook qui y est affichée comme URL de rappel et le jeton de vérification ci-dessous, et abonnez-vous au champ « messages ». Sans Gladys Plus, Gladys peut seulement envoyer. |
| Jeton de vérification | string | Non | Généré par l'intégration s'il est vide. Collez la même valeur dans l'application Meta (WhatsApp → Configuration → Jeton de vérification). |
| Enregistrer automatiquement le webhook chez Meta | boolean | Non | Nécessite l'identifiant du compte WhatsApp Business. Refait à chaque changement de l'URL Gladys Plus. |
| Hors de la fenêtre de 24 heures | section | Non | WhatsApp ne laisse une entreprise envoyer du texte libre que dans les 24 heures qui suivent le dernier message de l'utilisateur. Au-delà, seul un modèle de message approuvé passe. Créez un modèle de catégorie Utilitaire avec une seule variable dans le corps, par exemple « Gladys : {{1}} », et indiquez son nom ci-dessous : Gladys y fera alors passer ses notifications. |
| Modèle de secours | string | Non | Nom du modèle approuvé (minuscules, chiffres, tirets bas). Vide : les messages hors fenêtre ne sont pas remis. |
| Langue du modèle | string | Non | Code de langue du modèle, comme dans WhatsApp Manager : en_US, fr, de, es… |
| Marquer les messages reçus comme lus | boolean | Non | L'expéditeur voit les coches bleues dès que Gladys a reçu le message. |
| Langue des réponses | select | Non | Langue des quelques réponses que l'intégration envoie elle-même avant qu'un numéro soit lié (code de liaison accepté ou refusé). |
Comment installer WhatsApp dans Gladys
- Dans Gladys, ouvrez Intégrations : WhatsApp apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
- Cliquez sur Installer. Gladys télécharge l'image Docker (
ghcr.io/william-de71/gladys-whatsapp:0.1.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). - Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
- Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/William-De71/gladys-whatsapp.
WhatsApp 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
WhatsApp 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 William-De71, et non par l'équipe cœur de Gladys.
- Parcourir toutes les intégrations, natives et communautaires
- Créer et publier votre propre intégration externe
- Code source sur GitHub — source de cette documentation