Was ist neu beim Hermes WhatsApp-Setup

Wenn du unsere Hermes-Agent-Serie verfolgt hast, weißt du, dass wir es lieben, Dinge einfach zu halten. Heute tauchen wir in das aktualisierte WhatsApp-Setup ein – und unter der Haube gibt es eine große Änderung.

Hermes verbindet sich jetzt über eine eingebaute Bridge auf Basis von Baileys mit WhatsApp. Stell es dir vor wie das Emulieren einer WhatsApp-Web-Sitzung. Kein Meta-Entwicklerkonto, keine Business-Verifizierung, keine öffentliche URL – nur du, dein Telefon und ein QR-Code.

Schnellstart: Führe hermes gateway setup aus und wähle WhatsApp für eine geführte Einrichtung.

Zwei WhatsApp-Integrationen – den Unterschied kennen

Bevor wir weitermachen, klären wir einen häufigen Verwirrungspunkt. Es gibt zwei Möglichkeiten, WhatsApp mit Hermes zu verbinden:

Integration	Am besten geeignet für	Erfordert
Baileys-Bridge (diese Anleitung)	Persönliche Bots, schnelles Testen, keine öffentliche URL	Nur ein Telefon mit WhatsApp
WhatsApp Business Cloud API	Echte Business-Bots, Stabilität, null Ban-Risiko	Meta-Business-Konto, öffentliche Webhook-URL

Die Baileys-Bridge ist inoffiziell – sie birgt ein kleines Ban-Risiko. Die Business Cloud API ist der offizielle, von Meta unterstützte Weg. Du kannst sogar beide parallel auf verschiedenen Telefonnummern betreiben, wenn du das brauchst.

⚠️ Zwei wichtige Warnungen

Ban-Risiko: WhatsApp unterstützt offiziell keine Drittanbieter-Bots außerhalb der Business API. Um sicher zu bleiben:

Verwende eine dedizierte Telefonnummer für den Bot (nicht deine persönliche)
Sende keine Massen- oder Spam-Nachrichten – halte es konversationell
Automatisiere keine ausgehenden Nachrichten an Personen, die dir nicht zuerst geschrieben haben

Protokoll-Updates: WhatsApp aktualisiert regelmäßig sein Web-Protokoll, was Drittanbieter-Bridges vorübergehend stören kann. Wenn dein Bot nach einem WhatsApp-Update nicht mehr funktioniert, ziehe einfach die neueste Hermes-Version und kopple neu.

Zwei Modi – wähle deinen Stil

Modus	So funktioniert es	Am besten geeignet für
Separate Bot-Nummer (empfohlen)	Widme eine Nummer dem Bot; Leute schreiben ihr direkt	Saubere UX, mehrere Benutzer, geringeres Ban-Risiko
Persönlicher Selbst-Chat	Nutze dein eigenes WhatsApp; schreibe dir selbst, um mit dem Agenten zu sprechen	Schnelles Setup, einzelner Benutzer, Testen

Voraussetzungen

Node.js v18+ und npm – die Bridge läuft als Node.js-Prozess
Ein Telefon mit installiertem WhatsApp (zum Scannen des QR-Codes)

Gute Nachrichten: Die aktuelle Baileys-basierte Bridge benötigt kein Chromium oder Puppeteer mehr. Viel leichter.

Schritt 1: Den Setup-Assistenten ausführen

hermes whatsapp

Der Assistent wird:

Fragen, welchen Modus du möchtest (Bot oder Selbst-Chat)
Bridge-Abhängigkeiten installieren, falls nötig
Einen QR-Code in deinem Terminal anzeigen
Warten, bis du ihn scannst

So scannst du den QR-Code:

Öffne WhatsApp auf deinem Telefon
Gehe zu Einstellungen → Verknüpfte Geräte
Tippe auf Gerät verknüpfen
Halte deine Kamera auf den QR-Code im Terminal

Sobald die Kopplung abgeschlossen ist, bestätigt der Assistent die Verbindung und beendet sich. Deine Sitzung wird automatisch gespeichert.

Tipp: Wenn der QR-Code verzerrt aussieht, stelle sicher, dass dein Terminal mindestens 60 Spalten breit ist und Unicode unterstützt.

Schritt 2: Eine zweite Telefonnummer bekommen (Bot-Modus)

Für den Bot-Modus brauchst du eine Nummer, die noch nicht bei WhatsApp registriert ist. Drei Optionen:

Option	Kosten	Hinweise
Google Voice	Kostenlos	Nur USA. Verifiziere WhatsApp per SMS über die Google-Voice-App.
Prepaid-SIM	5–15 $ einmalig	Aktivieren, verifizieren, dann kann die SIM in der Schublade liegen. Alle 90 Tage einmal anrufen, um sie aktiv zu halten.
VoIP-Dienste	Kostenlos–5 $/Monat	TextNow, TextFree, etc. Einige Nummern werden von WhatsApp blockiert – probiere ein paar aus.

Nachdem du die Nummer hast:

Installiere WhatsApp auf einem Telefon (oder nutze die WhatsApp-Business-App mit Dual-SIM)
Registriere die neue Nummer
Führe hermes whatsapp aus und scanne den QR-Code von diesem Konto aus

Schritt 3: Hermes konfigurieren

Füge dies zu deiner ~/.hermes/.env-Datei hinzu:

# Erforderlich
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot                          # "bot" oder "self-chat"

# Zugriffskontrolle – wähle EINES:
WHATSAPP_ALLOWED_USERS=15551234567         # Kommagetrennte Nummern (Ländercode, ohne +)
# WHATSAPP_ALLOWED_USERS=*                 # ODER erlaube allen
# WHATSAPP_ALLOW_ALL_USERS=true            # ODER setze dieses Flag (gleich wie *)

Alle-erlauben-Kurzform: Das Setzen von WHATSAPP_ALLOWED_USERS=* erlaubt allen Absendern – gleichbedeutend mit WHATSAPP_ALLOW_ALL_USERS=true. Um stattdessen den Pairing-Flow zu nutzen, entferne beide Variablen und verlasse dich auf das DM-Pairing-System.

Optionale Einstellungen in ~/.hermes/config.yaml:

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

pair (globaler Standard) sendet unbekannten DM-Absendern einen Pairing-Code.
ignore hält WhatsApp für nicht autorisierte DMs still – normalerweise besser für eine private Nummer.

Starte dann das Gateway:

hermes gateway              # Vordergrund
hermes gateway install      # Als Benutzerdienst installieren
sudo hermes gateway install --system   # Linux: Systemdienst beim Booten

Sitzungspersistenz & erneutes Koppeln

Die Bridge speichert ihre Sitzung unter ~/.hermes/platforms/whatsapp/session. Das bedeutet:

Sitzungen überleben Neustarts – kein erneutes Scannen jedes Mal
Sitzungsdaten enthalten Verschlüsselungsschlüssel und Geräte-Anmeldedaten
Teile oder committe dieses Verzeichnis nicht – es gewährt vollen Zugriff auf das Konto

Wenn die Sitzung bricht (Telefon-Reset, WhatsApp-Update, manuelles Entkoppeln), siehst du Verbindungsfehler in den Logs. Behebe es, indem du ausführst:

hermes whatsapp

Das erzeugt einen frischen QR-Code zum erneuten Koppeln.

Das war das neue WhatsApp-Setup in Kürze. Schnell, leichtgewichtig und kein Meta-Papierkram. Als Nächstes in der Serie: Wir vergleichen diese Bridge direkt mit der WhatsApp Business Cloud API – bleib dran!