Nouveautés de la configuration WhatsApp de Hermes

Si vous suivez notre série sur l’agent Hermes, vous savez que nous adorons simplifier les choses. Aujourd’hui, on plonge dans la configuration WhatsApp mise à jour — et il y a un gros changement sous le capot.

Hermes se connecte désormais à WhatsApp via un pont intégré basé sur Baileys. Considérez-le comme une émulation de session WhatsApp Web. Pas de compte développeur Meta, pas de vérification Business, pas d’URL publique — juste vous, votre téléphone et un QR code.

Démarrage rapide : Lancez hermes gateway setup et choisissez WhatsApp pour un accompagnement pas à pas.

Deux intégrations WhatsApp — Comprendre la différence

Avant d’aller plus loin, clarifions un point qui prête souvent à confusion. Il existe deux façons de connecter WhatsApp à Hermes :

Intégration	Idéale pour	Nécessite
Pont Baileys (ce guide)	Bots personnels, tests rapides, pas d’URL publique	Juste un téléphone avec WhatsApp
API WhatsApp Business Cloud	Vrais bots professionnels, stabilité, zéro risque de bannissement	Compte Meta Business, URL webhook publique

Le pont Baileys est non officiel — il comporte un léger risque de bannissement. L’API Business Cloud est le chemin officiel soutenu par Meta. Vous pouvez même exécuter les deux en parallèle sur des numéros différents si nécessaire.

⚠️ Deux avertissements importants

Risque de bannissement : WhatsApp ne prend pas officiellement en charge les bots tiers en dehors de l’API Business. Pour rester en sécurité :

Utilisez un numéro dédié pour le bot (pas votre numéro personnel)
N’envoyez pas de messages en masse ou de spam — restez dans la conversation
N’automatisez pas les messages sortants vers des personnes qui ne vous ont pas écrit en premier

Mises à jour du protocole : WhatsApp met régulièrement à jour son protocole Web, ce qui peut temporairement casser les ponts tiers. Si votre bot cesse de fonctionner après une mise à jour de WhatsApp, récupérez simplement la dernière version de Hermes et réappairez.

Deux modes — Choisissez votre style

Mode	Comment ça marche	Idéal pour
Numéro de bot séparé (recommandé)	Dédiez un numéro au bot ; les gens lui écrivent directement	UX propre, plusieurs utilisateurs, risque de bannissement réduit
Auto-discussion personnelle	Utilisez votre propre WhatsApp ; écrivez-vous à vous-même pour parler à l’agent	Configuration rapide, utilisateur unique, tests

Prérequis

Node.js v18+ et npm — le pont fonctionne comme un processus Node.js
Un téléphone avec WhatsApp installé (pour scanner le QR code)

Bonne nouvelle : le pont actuel basé sur Baileys ne nécessite plus Chromium ni Puppeteer. Beaucoup plus léger.

Étape 1 : Lancer l’assistant de configuration

hermes whatsapp

L’assistant va :

Demander quel mode vous voulez (bot ou auto-discussion)
Installer les dépendances du pont si nécessaire
Afficher un QR code dans votre terminal
Attendre que vous le scanniez

Pour scanner le QR code :

Ouvrez WhatsApp sur votre téléphone
Allez dans Paramètres → Appareils connectés
Appuyez sur Connecter un appareil
Pointez votre caméra vers le QR code du terminal

Une fois appairé, l’assistant confirme la connexion et se ferme. Votre session est enregistrée automatiquement.

Astuce : Si le QR code semble illisible, assurez-vous que votre terminal fait au moins 60 colonnes de large et prend en charge Unicode.

Étape 2 : Obtenir un deuxième numéro (mode bot)

Pour le mode bot, vous avez besoin d’un numéro pas déjà enregistré sur WhatsApp. Trois options :

Option	Coût	Remarques
Google Voice	Gratuit	États-Unis uniquement. Vérifiez WhatsApp par SMS via l’application Google Voice.
Carte SIM prépayée	5–15 $ une fois	Activez, vérifiez, puis la SIM peut rester dans un tiroir. Appelez tous les 90 jours pour la garder active.
Services VoIP	Gratuit–5 $/mois	TextNow, TextFree, etc. Certains numéros sont bloqués par WhatsApp — essayez-en plusieurs.

Après avoir obtenu le numéro :

Installez WhatsApp sur un téléphone (ou utilisez l’application WhatsApp Business avec double SIM)
Enregistrez le nouveau numéro
Lancez hermes whatsapp et scannez le QR code depuis ce compte

Étape 3 : Configurer Hermes

Ajoutez ceci à votre fichier ~/.hermes/.env :

# Requis
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot                          # "bot" ou "self-chat"

# Contrôle d’accès — choisissez UNE option :
WHATSAPP_ALLOWED_USERS=15551234567         # Numéros séparés par des virgules (indicatif pays, sans +)
# WHATSAPP_ALLOWED_USERS=*                 # OU autoriser tout le monde
# WHATSAPP_ALLOW_ALL_USERS=true            # OU définir ce drapeau (équivalent à *)

Raccourci tout-autoriser : Définir WHATSAPP_ALLOWED_USERS=* autorise tous les expéditeurs — équivalent à WHATSAPP_ALLOW_ALL_USERS=true. Pour utiliser le flux d’appairage à la place, supprimez les deux variables et reposez-vous sur le système d’appairage par message direct.

Paramètres optionnels dans ~/.hermes/config.yaml :

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

pair (défaut global) envoie un code d’appairage aux expéditeurs de messages directs inconnus.
ignore garde WhatsApp silencieux pour les messages directs non autorisés — généralement mieux pour un numéro privé.

Ensuite, démarrez la passerelle :

hermes gateway              # Premier plan
hermes gateway install      # Installer comme service utilisateur
sudo hermes gateway install --system   # Linux : service système au démarrage

Persistance de session et ré-appairage

Le pont enregistre sa session dans ~/.hermes/platforms/whatsapp/session. Cela signifie :

Les sessions survivent aux redémarrages — pas besoin de re-scanner à chaque fois
Les données de session incluent les clés de chiffrement et les identifiants de l’appareil
Ne partagez pas et ne committez pas ce dossier — il donne un accès complet au compte

Si la session se casse (réinitialisation du téléphone, mise à jour WhatsApp, dissociation manuelle), vous verrez des erreurs de connexion dans les journaux. Corrigez en lançant :

hermes whatsapp

Cela génère un nouveau QR code pour ré-appairer.

Voilà en résumé la nouvelle configuration WhatsApp. Rapide, légère, et sans paperasse Meta. Prochain épisode de la série : nous comparerons ce pont côte à côte avec l’API WhatsApp Business Cloud — restez à l’écoute !