Hermes Agent vient de sortir une intégration WhatsApp Business Cloud de qualité production. Concrètement : tu peux maintenant brancher ton agent IA sur WhatsApp — pour toi, ton équipe, ou tes clients — via l'API officielle de Meta. Pas de bridge Node.js, pas de QR code, pas de risque de bannissement de compte. Voici ce que la maj débloque, et comment la mettre en place proprement.
1Pourquoi c'est la voie de prod (et pas un hack)
Brancher WhatsApp « gratuitement » via une lib non officielle qui scanne un QR code, ça marche en démo — mais Meta finit par couper le numéro. Hermes propose les deux chemins ; pour un bot que tes clients utilisent vraiment, tu prends l'officiel.
| Critère | Bridge Baileyshermes whatsapp | API Cloudhermes whatsapp-cloud |
|---|---|---|
| Type de compte | Perso | WhatsApp Business |
| Mise en place | Scan QR code | App Meta + numéro + token |
| URL publique requise ? | Non | Oui (webhook) |
| Risque de ban | Oui (non officiel) | Non (supporté par Meta) |
| Accusés de lecture / saisie | Non | Oui |
| Usage client final | Risqué | ★ Conçu pour ça |
2Le setup guidé : hermes whatsapp-cloud
Tu ne fais pas tout à la main. La commande hermes whatsapp-cloud lance un assistant qui te demande chaque identifiant, le valide au moment où tu le colles, et imprime les instructions exactes pour les étapes qui se passent hors de l'assistant (lancer le tunnel, configurer le webhook côté Meta).
3Les prérequis Meta + les 4 identifiants
Avant de lancer l'assistant. Il te faut un compte Meta Business (pas ton WhatsApp perso), une app Meta avec WhatsApp activé, et un compte WhatsApp Business (WABA) rattaché. Le bot tourne sur un numéro business dédié, pas ton numéro perso.
L'assistant te réclame ensuite ces 4 valeurs, dans cet ordre — voici la forme exacte pour ne pas te tromper de champ :
| Identifiant | Forme | Rôle |
|---|---|---|
| Phone Number ID | 15-17 chiffres | ID interne Meta du numéro (≠ le numéro) |
| Access Token | commence par EAA | L'identité de ton bot pour envoyer |
| App Secret | 32 caractères hex | Vérifie la signature des entrants |
| Verify Token | généré par l'assistant | Poignée de main du webhook |
4Rendre Hermes joignable par Meta (le webhook)
Le principe. L'API Cloud livre les messages entrants par un appel HTTPS sur ta passerelle Hermes. Donc hermes gateway doit être joignable depuis l'extérieur, en HTTPS. Pas besoin d'ouvrir un port ni d'avoir un domaine : un tunnel suffit.
La méthode simple. Cloudflare Tunnel (cloudflared) — gratuit, sans compte, sans redirection de port. Une commande te donne une URL https://<aléatoire>.trycloudflare.com : c'est elle que tu donnes à Meta. Meta tape ton URL en GET, Hermes renvoie le « challenge », Meta valide. Ensuite tu t'abonnes au champ messages — c'est ça qui déclenche la livraison réelle des entrants.
cloudflared. Pour un bot en continu, crée un tunnel nommé (compte Cloudflare gratuit, URL stable) — sinon, à chaque reboot, tu dois remettre à jour l'URL côté Meta.5La règle des 24h de Meta (à connaître AVANT de promettre)
La contrainte que personne ne voit venir. Meta n'autorise les messages libres que dans une fenêtre de 24h après le dernier message du client. Au-delà, seul un template pré-approuvé passe. Ce n'est pas une limite d'Hermes — c'est la règle « fenêtre de service client » de Meta.
6Sécurité : tout vit dans ~/.hermes/.env
Token temporaire vs token de prod. Le token généré dans le tableau de bord Meta expire au bout de 24h — utile pour tester, inutilisable en prod (ton bot tombe le lendemain). Pour la production, tu crées un System User token permanent (permissions messaging WhatsApp, expiration « jamais »), tu le mets dans ~/.hermes/.env, et tu redémarres la passerelle.
• App Secret → comme un mot de passe. Qui l'a peut forger de faux entrants qu'Hermes acceptera comme authentiques.
• Access Token → l'identité du bot, équivalent d'une clé d'API longue durée. Compromis ? Révoque tout de suite.
• Verify Token → enjeu plus faible, mais à ne pas committer non plus.
WHATSAPP_CLOUD_ALLOWED_USERS). Par défaut, sans allowlist, tout entrant est refusé — c'est voulu : personne ne peut piloter ton bot avec un numéro inconnu.Le récap, dans l'ordre
Si tu lances ça ce soir avec hermes whatsapp-cloud, voici la séquence — chaque étape débloque la suivante.
| # | Étape | Le point d'attention |
|---|---|---|
| 1 | Compte Business + app Meta + WABA | Numéro business dédié, pas le perso |
| 2 | hermes whatsapp-cloud → coller les 4 identifiants | ★ Phone Number ID ≠ numéro |
| 3 | Lancer un tunnel HTTPS + hermes gateway | URL stable (tunnel nommé) |
| 4 | Configurer + vérifier le webhook côté Meta | S'abonner au champ messages |
| 5 | Allowlist + token permanent | System User, expiration « jamais » |
