Hermes Agent sur WhatsApp ne se connecte pas : solutions

Le bot ne répond jamais et les logs sont muets

Vous avez branché Hermes Agent sur WhatsApp, la gateway démarre sans erreur, et le numéro auquel vous écrivez reste inerte. Aucun événement entrant dans les logs, aucun accusé de réception sur le téléphone, aucune piste claire sur laquelle des dix pièces mobiles est cassée. WhatsApp est le canal le plus fragile du stack Hermes, et presque tous les cas de connexion silencieuse se ramènent à l'une de quatre causes.

Trois des quatre échouent en silence par conception, ce qui explique pourquoi la configuration a l'air correcte alors que rien ne marche. Ce post parcourt chaque cause, comment confirmer que c'est la vôtre, et la solution exacte. Commencez par la première - l'ordre compte, parce que c'est celle qui piège tout le monde depuis mai 2026.

Cause 1 : WhatsApp Shortcake a cassé votre librairie QR

Si vous exécutez Hermes Agent via Baileys, WAHA, ou toute autre librairie qui scrape WhatsApp Web, et que le QR refuse d'être scanné ou déconnecte le bot juste après, vous butez sur le déploiement Shortcake pour les appareils liés. WhatsApp exige désormais une passkey WebAuthn sur l'appareil lié, et un serveur headless n'a pas de passkey à présenter : navigator.credentials.get() échoue et le lien est rejeté avec un 428.

Symptôme : le QR s'affiche, votre téléphone le scanne, et soit l'appairage ne se termine jamais, soit la session meurt en quelques minutes. Les anciennes sessions qui se reconnectaient toutes seules ont commencé à renvoyer Stream Errored (conflict) après mai 2026 pour la même raison. Si ça marchait en avril et a cessé de marcher du jour au lendemain, c'est votre cause.

La solution a deux formes :

Passez à la Cloud API officielle. C'est le chemin supporté, il n'est pas vulnérable à Meta cassant une librairie de scraping un mardi au hasard, et c'est ce que le reste du post suppose. Configurez Hermes Agent avec WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID et WHATSAPP_WEBHOOK_VERIFY_TOKEN au lieu du flux QR. Le guide de déploiement WhatsApp déroule toute la danse des identifiants.
Restez sur Baileys si vous n'avez pas le choix, et épinglez le commit exact qui marche encore pour vous (les mainteneurs suivent les contournements passkey dans l'issue #2672). Acceptez que le prochain changement côté Meta vous casse à nouveau. Ce n'est pas le bon choix pour quoi que ce soit dont vous dépendez.

Le reste du post couvre le chemin Cloud API.

Cause 2 : votre WABA n'est pas abonnée à votre app

C'est l'échec le plus courant de la Cloud API et le plus silencieux. Vous mettez l'URL du webhook dans le App Dashboard, le GET de vérification passe, Meta affiche une coche verte à côté de l'endpoint, et aucun événement de message n'arrive jamais.

Ce qui se passe : fixer l'URL du webhook sur l'app n'est que la moitié du câblage. Chaque WhatsApp Business Account (WABA) doit s'abonner séparément à cette app pour que ses messages soient routés vers votre endpoint. Le App Dashboard n'affiche cet abonnement nulle part, et l'UI du webhook vous laisse finir le setup sans WABA rattachée. Meta appelle ça le problème de shadow delivery et la solution est un appel d'API que l'assistant de setup ne mentionne pas.

Vérifiez d'abord :

curl -s "https://graph.facebook.com/v20.0/<WABA_ID>/subscribed_apps" \
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN"

Si le tableau data est vide ou ne contient pas l'ID de votre app, c'est votre problème.

La solution :

curl -X POST "https://graph.facebook.com/v20.0/<WABA_ID>/subscribed_apps" \
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN"

L'appel renvoie {"success": true} et le message entrant suivant arrive sur le webhook Hermes Agent en quelques secondes. Pas besoin de redémarrer la gateway. Si vous faites tourner le token plus tard, relancez cet appel : l'abonnement est lié à l'app mais l'écriture demande un token avec la permission whatsapp_business_management.

Cause 3 : vous utilisez encore le token temporaire de 24 heures

Le token que Meta affiche sur l'écran de setup WhatsApp expire en exactement 24 heures. Si vous l'avez copié dans le .env de Hermes Agent mardi après-midi et que le bot est devenu muet mercredi après-midi, c'est pour ça.

Symptôme : votre gateway logue OAuthException ou HTTP 401 sur le prochain envoi sortant après l'expiration. Les appels webhook entrants de Meta peuvent continuer d'arriver (ils n'ont pas besoin de votre token) mais chaque réponse que Hermes tente de renvoyer échoue, donc le bot reçoit votre message, génère une réponse et la perd en chemin.

La solution est un token permanent de System User, pas un token temporaire plus long :

Dans Meta Business Suite ouvrez Users puis System Users et créez un nouveau System User avec le rôle Admin.
Assignez votre app WhatsApp et votre WhatsApp Business Account à ce System User avec Full control.
Cliquez Generate new token, choisissez votre app, et cochez à la fois whatsapp_business_messaging (nécessaire pour envoyer) et whatsapp_business_management (nécessaire pour l'appel subscribed_apps de la Cause 2).
Mettez l'expiration sur Never. Copiez le token, mettez-le dans WHATSAPP_ACCESS_TOKEN, redémarrez la gateway.

Vérifiez avant de partir :

curl -s "https://graph.facebook.com/v20.0/me?access_token=$WHATSAPP_ACCESS_TOKEN"

Doit renvoyer l'ID et le nom de votre System User, pas une erreur OAuth.

Cause 4 : vous envoyez au mauvais Phone Number ID

La Cloud API WhatsApp utilise trois identifiants et tous sont faciles à confondre : le numéro de téléphone lui-même, le Phone Number ID, et le WABA ID. Hermes Agent a besoin du Phone Number ID, pas du numéro. Si vous avez collé le numéro dans WHATSAPP_PHONE_NUMBER_ID, chaque appel sortant renvoie Object with ID '+33...' does not exist et chaque entrée arrive sans route de retour.

Pour compliquer, le Phone Number ID est un nombre de 15 ou 16 chiffres qui ressemble beaucoup à un téléphone. Ce n'est pas un téléphone.

Où le trouver : dans le App Dashboard, ouvrez WhatsApp puis API Setup. Le menu déroulant From liste vos numéros enregistrés. Sous chaque numéro, en petit, se trouve un champ intitulé Phone number ID. C'est la valeur dont Hermes Agent a besoin.

Vérifiez que la valeur que vous avez est réelle :

curl -s "https://graph.facebook.com/v20.0/$WHATSAPP_PHONE_NUMBER_ID?access_token=$WHATSAPP_ACCESS_TOKEN"

Un ID valide renvoie display_phone_number, verified_name, et quality_rating. Un mauvais ID renvoie une erreur du Graph API dont le message nomme l'ID introuvable.

Tant que vous y êtes, vérifiez la variable WHATSAPP_BUSINESS_ACCOUNT_ID : c'est un ID distinct pour la WABA propriétaire du numéro, utilisé par l'appel d'abonnement de la Cause 2, et c'est facile d'inverser les deux quand vous les copiez depuis le dashboard.

Deux pièges de plus à écarter

Si les quatre causes ci-dessus sont propres et que les messages ne circulent toujours pas, vérifiez ensuite :

L'app est bloquée en mode Dev. WhatsApp ne livre les webhooks que pour les messages que le propriétaire de l'app a envoyés ou reçus dans les dernières 24 heures, et uniquement depuis les numéros ajoutés explicitement dans WhatsApp puis API Setup puis To. Passez l'app en Live dans App Review quand vous êtes prêt pour du trafic réel.
Le champ webhook messages n'est pas abonné. Dans WhatsApp puis Configuration, regardez la section Webhook fields et confirmez que messages a une coche verte. Meta vous laisse enregistrer une URL de webhook sans champs abonnés, et ne livre silencieusement rien.

Ordre de diagnostic qui fait gagner du temps

Quand le bot devient muet, parcourez les causes dans cet ordre plutôt que de tout réinstaller :

Êtes-vous sur le chemin QR ? Si oui, migrez vers la Cloud API avant de perdre une minute de plus sur autre chose. Shortcake ne s'en va pas.
Votre WABA est-elle abonnée à votre app ? Le seul appel curl ci-dessus y répond en trois secondes. Le taux de réussite le plus haut sur les déploiements Cloud API.
Vérifiez le token. curl /me échoue immédiatement si le token est mort, faux ou sans scopes.
Vérifiez le Phone Number ID. curl /$PHONE_NUMBER_ID renvoie les champs du numéro quand il est valide.
Vérifiez le mode Dev et les champs abonnés. Plus lent à inspecter, moins courant comme cause racine, mais à écarter avant d'ouvrir un ticket avec Meta.

Pour le chemin d'installation complet, voir le guide de déploiement Hermes Agent sur WhatsApp. Si Telegram peut convenir, la comparaison Telegram vs WhatsApp parcourt les compromis avant de vous engager.

Quand vous préférez ne pas vous battre avec Meta chaque semaine

Meta livre des changements d'UI webhook, durcit la vérification et casse le chemin QR à son rythme. Si pour vous un agent IA personnel ne devrait pas exiger un compte Business Manager et un token System User pour dire bonjour, lancez-vous avec Hermify. Hermify exécute un Hermes Agent géré sur Telegram avec la même mémoire et les mêmes skills, en ligne en une minute environ, sans configuration Meta à surveiller.