WhatsApp — KI für den meistgenutzten Chat der Welt

WhatsApp ist überall. Über zwei Milliarden Menschen nutzen es täglich, und jetzt kannst du Hermes direkt darin einbinden. Kein Meta-Entwicklerkonto. Keine Unternehmensverifizierung. Kein kompliziertes API-Setup. Einfach einen QR-Code scannen und schon sprichst du mit deinem KI-Agenten aus derselben App, mit der du deinen Freunden schreibst.

So funktioniert’s

Hermes verbindet sich über eine eingebaute Brücke auf Basis von Baileys mit WhatsApp. Stell es dir vor wie eine Emulation einer WhatsApp-Web-Sitzung — genauso, wie du einen Browser mit deinem Telefon verknüpfst. Es ist nicht die offizielle WhatsApp-Business-API, was bedeutet, dass du keine speziellen Genehmigungen brauchst, um loszulegen.

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

Zwei Verwendungsmöglichkeiten

Modus	So funktioniert’s	Am besten geeignet für
Separate Bot-Nummer (empfohlen)	Eine Telefonnummer wird dem Bot zugewiesen. Leute schreiben dieser Nummer direkt.	Saubere UX, mehrere Nutzer, geringeres Sperrrisiko
Persönlicher Selbst-Chat	Du nutzt dein eigenes WhatsApp. Du schreibst dir selbst, um mit dem Agenten zu sprechen.	Schnelle Einrichtung, einzelner Nutzer, Tests

Der Ansatz mit der separaten Bot-Nummer ist sauberer — deine KI hat eine eigene Identität, und du vermischst persönliche Chats nicht mit Bot-Unterhaltungen. Der Selbst-Chat-Modus ist perfekt für einen schnellen Testlauf.

Bevor du loslegst

Du brauchst:

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

Gute Nachrichten: Anders als bei älteren browserbasierten Brücken musst du weder Chromium noch Puppeteer installieren. Das Setup ist deutlich schlanker.

Schritt 1: Den Setup-Assistenten ausführen

hermes whatsapp

Der Assistent wird:

Fragen, welchen Modus du möchtest (Bot oder Selbst-Chat)
Bei Bedarf Brücken-Abhängigkeiten installieren
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. Du kannst auch einen anderen Terminal-Emulator ausprobieren.

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

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

Option	Kosten	Hinweise
Google Voice	Kostenlos	Nur USA. Hol dir eine Nummer unter voice.google.com. Verifiziere WhatsApp per SMS über die Google-Voice-App.
Prepaid-SIM	5–15 $ einmalig	Jeder Anbieter. Aktivieren, WhatsApp verifizieren, dann kann die SIM in der Schublade liegen. Die Nummer muss aktiv bleiben (alle 90 Tage ein Anruf).
VoIP-Dienste	Kostenlos–5 $/Monat	TextNow, TextFree oder Ähnliches. Einige VoIP-Nummern werden von WhatsApp blockiert — probiere ein paar aus, wenn die erste nicht funktioniert.

Nachdem du die Nummer hast:

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

Schritt 3: Hermes konfigurieren

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

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

# Zugriffskontrolle — wähle EINE dieser Optionen:
WHATSAPP_ALLOWED_USERS=15551234567         # Kommagetrennte Telefonnummern (mit Ländercode, ohne +)
# WHATSAPP_ALLOWED_USERS=*                 # ODER verwende *, um alle zuzulassen
# WHATSAPP_ALLOW_ALL_USERS=true            # ODER setze dieses Flag stattdessen (gleicher Effekt wie *)

Alle-zulassen-Abkürzung: Das Setzen von WHATSAPP_ALLOWED_USERS=* erlaubt allen Absendern den Zugriff. Um stattdessen den Kopplungsablauf zu verwenden, entferne beide Variablen und verlasse dich auf das DM-Kopplungssystem.

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

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

unauthorized_dm_behavior: pair ist die globale Standardeinstellung. Unbekannte DM-Absender erhalten einen Kopplungscode.
whatsapp.unauthorized_dm_behavior: ignore sorgt dafür, dass WhatsApp bei nicht autorisierten DMs still bleibt — normalerweise die bessere Wahl für eine private Nummer.

Starte dann das Gateway:

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

Das Gateway startet die WhatsApp-Brücke automatisch mit der gespeicherten Sitzung.

Sitzungspersistenz

Die Baileys-Brücke speichert ihre Sitzung unter ~/.hermes/platforms/whatsapp/session. Das bedeutet:

Sitzungen überleben Neustarts — du musst den QR-Code nicht jedes Mal neu scannen
Die Sitzungsdaten enthalten Verschlüsselungsschlüssel und Geräteanmeldeinformationen
Teile oder committe dieses Sitzungsverzeichnis nicht — es gewährt vollen Zugriff auf das WhatsApp-Konto

Neu-Kopplung

Wenn die Sitzung bricht (Telefon-Reset, WhatsApp-Update, manuelles Entkoppeln), siehst du Verbindungsfehler in den Gateway-Logs. So behebst du es:

hermes whatsapp

Das erzeugt einen frischen QR-Code zur erneuten Kopplung.

Ein Wort der Vorsicht

WhatsApp unterstützt offiziell keine Drittanbieter-Bots außerhalb der Business-API. Die Verwendung einer Drittanbieter-Brücke birgt ein geringes Risiko von Kontoeinschränkungen. Um das Risiko zu minimieren:

Verwende eine dedizierte Telefonnummer für den Bot (nicht deine persönliche Nummer)
Sende keine Massen-/Spam-Nachrichten — halte die Nutzung gesprächsorientiert
Automatisiere keine ausgehenden Nachrichten an Personen, die nicht zuerst geschrieben haben

Außerdem aktualisiert WhatsApp regelmäßig sein Web-Protokoll, was die Kompatibilität mit Drittanbieter-Brücken vorübergehend brechen kann. Wenn das passiert, wird Hermes die Brücken-Abhängigkeit aktualisieren. Wenn der Bot nach einem WhatsApp-Update nicht mehr funktioniert, ziehe die neueste Hermes-Version und kopple neu.

Du möchtest etwas Offizielleres?

Wenn du einen echten Geschäfts-Bot betreibst und Stabilität brauchst, schau dir stattdessen den WhatsApp-Business-Cloud-API-Leitfaden an. Das ist der offizielle, von Meta unterstützte Weg: kein Kontosperrrisiko, erfordert aber ein Meta-Business-Konto und eine öffentliche Webhook-URL. Die beiden Adapter können auch parallel mit verschiedenen Telefonnummern laufen, falls du einen Grund dafür hast.

Für die meisten persönlichen Projekte und Experimente ist die Baileys-Brücke allerdings der schnellste Weg, KI in dein WhatsApp zu bringen. Scannen, konfigurieren und loschatten.