# Kapitel 18 – WAHA (WhatsApp HTTP API) ## Einleitung WhatsApp ist – ob man es mag oder nicht – der meistgenutzte Messenger der westlichen Welt. Für viele Creator:innen, Communities oder Teams ist er daher ein unvermeidlicher Teil der Kommunikationsstruktur – egal ob für Zuschauer:innen‑Kontakt, Event‑Ankündigungen oder automatisierte Benachrichtigungen. **WAHA** (WhatsApp HTTP API) ist ein selbstgehosteter Dienst, der ein zentrales Problem löst: WhatsApp lässt sich im Gegensatz zu Telegram, Discord oder Signal **nicht über offene APIs** ansprechen – automatisierte Nachrichten oder Integrationen sind offiziell nur über die Meta‑Cloud möglich und mit hohen Hürden verbunden. WAHA umgeht diese Beschränkung, indem es das **Web‑Interface von WhatsApp** lokal emuliert. So kannst du Nachrichten senden und empfangen – ohne Drittanbieter, ohne Cloud, direkt aus deinem eigenen Netzwerk. In diesem Kapitel richtest du WAHA als dedizierten **LXC-Container** in deinem UCC ein. Du verbindest den Dienst mit einem separaten WhatsApp‑Konto und ermöglichst so den automatisierten Empfang und Versand von Nachrichten – z. B. zur Trigger-Auslösung in Workflows, als Rückkanal für Zuschauer:innen oder zur Weiterleitung interner Systemereignisse. 👉 **Screenshot geeignet:** UCC-Dashboard mit markiertem WAHA‑Container, neben n8n und NPM > [!NOTE] > WAHA simuliert ein WhatsApp‑Web‑Interface und benötigt daher ein physisches Gerät mit aktiver WhatsApp‑Installation. > Diese Lösung eignet sich **nicht für produktive Massenkommunikation** oder den Ersatz offizieller WhatsApp‑Business‑APIs, > sondern für individuelle, datensparsame Anwendungsfälle – z. B. private Rückkanäle, automatisierte Antworten, > Kontaktformulare, Zustellbenachrichtigungen oder Info‑Trigger im Streaming‑Kontext. WAHA arbeitet vollständig lokal, speichert keine Nachrichten extern und lässt sich direkt mit Diensten wie **n8n**, **Webhook‑Empfängern** oder benutzerdefiniertem Backend verbinden. So entsteht eine WhatsApp‑Schnittstelle, die exakt das tut, was du brauchst – nicht mehr und nicht weniger. 👉 **Screenshot geeignet:** Browseransicht WAHA‑Webinterface mit QR‑Code für WhatsApp‑Verknüpfung --- ## Voraussetzungen & Ressourcen WAHA ist leichtgewichtig, benötigt aber eine stabile Umgebung für das Webinterface, die Protokollierung und die Echtzeit‑Verarbeitung eingehender Nachrichten. Im Hintergrund laufen Headless‑Browserprozesse, Socket‑Verbindungen und eine kleine HTTP‑API – alles innerhalb eines Containers. Um Störungen bei der Kommunikation zu vermeiden, sollte die Umgebung klar definiert und zuverlässig sein. ### Container-Ressourcen * **CPU:** 2 vCPU Erforderlich für parallele Prozesse wie WebSocket‑Verbindungen, Headless-Browser (z. B. Chromium) und API-Handling. * **RAM:** 2 GB Ausreichend für den stabilen Betrieb von WAHA, inklusive temporärer Pufferspeicherung eingehender und ausgehender Daten. * **Speicherplatz:** 10 GB Deckt das Betriebssystem, Logs, temporäre Browserdaten und gespeicherte Sessions ab. Reicht im Dauerbetrieb vollständig aus, auch mit mehreren Verbindungen. * **Netzwerk:** Statische IP oder DHCP-Reservierung Notwendig für saubere Proxy-Integration und externe Webhook-Zugriffe. * **Betriebssystem:** Debian 12 (Bookworm) Schlank, stabil und optimal geeignet für den Einsatz von Docker und Headless-Browsern in Containerumgebungen. 👉 **Screenshot geeignet:** Ressourcenübersicht beim Erstellen des WAHA-LXC (vCPU 2 | RAM 2 GB | Storage 10 GB | Debian 12) ### Technische Voraussetzungen Vor der Einrichtung sollte dein UCC folgende Voraussetzungen erfüllen: * **Proxmox VE** ist aktiv und bereit zur Containererstellung. Der WAHA-Container wird wie gewohnt direkt über die Proxmox-Oberfläche angelegt. * **Nginx Proxy Manager (NPM)** ist installiert und erreichbar. WAHA wird später über eine eigene Subdomain bereitgestellt. * **DNS- oder DynDNS-Eintrag** für `waha.deinedomain.tld` ist vorhanden. Dieser wird für das SSL-Zertifikat und die WhatsApp-Webverbindung benötigt. * **Internetverbindung** im Container ist stabil. WAHA benötigt Zugriff auf WhatsApp‑Server (Webschnittstelle) und lädt initial alle Pakete über offizielle Repositories. * **SSH-Zugriff** auf den Container ist möglich, z. B. per: ```bash ssh root@ ``` Ersetze `` durch die tatsächliche Adresse deines WAHA‑LXC. > [!IMPORTANT] > Der Container sollte auf einem Host mit stabiler Netzwerkverbindung laufen. > Kurze Unterbrechungen führen zu Sessionabbrüchen und trennen die WhatsApp‑Verbindung – > in diesem Fall muss der QR‑Code erneut gescannt werden. 👉 **Screenshot geeignet:** Proxmox-Interface mit markiertem WAHA-LXC in der Containerliste --- ## Schritt-für-Schritt-Anleitung ### Schritt 1 – Container vorbereiten und System aktualisieren Starte den frisch erstellten WAHA‑Container in Proxmox und öffne die Konsole – entweder direkt über das Webinterface oder per SSH. Zuerst werden alle Systempakete auf den aktuellen Stand gebracht: ```bash apt update && apt upgrade -y ``` Nach Abschluss den Container neu starten: ```bash reboot ``` Anschließend erneut per SSH anmelden: ```bash ssh root@ ``` > [!NOTE] > Ein aktuelles System ist Pflicht. > WAHA benötigt moderne Pakete für Netzwerk, TLS und Headless-Browser‑Support. > Veraltete Images führen häufig zu Abbrüchen bei der WebSocket‑Verbindung oder zu Inkompatibilitäten beim Start. 👉 **Screenshot geeignet:** Proxmox-Konsole mit erfolgreichem Abschluss von `apt upgrade` (alle Pakete aktuell) ### Schritt 2 – Docker installieren und vorbereiten WAHA läuft vollständig in Docker-Containern. Damit die Umgebung stabil funktioniert, installierst du zunächst alle benötigten Pakete für Docker und Docker Compose. ```bash apt install -y ca-certificates curl gnupg lsb-release ``` Nun wird das offizielle Docker-Repository hinzugefügt und die aktuelle Engine installiert: ```bash mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \ https://download.docker.com/linux/debian $(lsb_release -cs) stable" \ | tee /etc/apt/sources.list.d/docker.list > /dev/null apt update apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ``` Prüfe anschließend, ob Docker korrekt installiert wurde: ```bash docker --version docker compose version ``` Die Ausgabe sollte in etwa so aussehen: ``` Docker version 26.1.x Docker Compose version v2.29.x ``` > [!NOTE] > WAHA nutzt Docker Compose als bevorzugte Installationsmethode. > Manuelle Setups ohne Compose werden von der Community zwar unterstützt, > sind aber deutlich fehleranfälliger und erschweren spätere Updates. 👉 **Screenshot geeignet:** Terminalausgabe mit sichtbarer Docker- und Compose-Version nach erfolgreicher Installation ### Schritt 3 – Verzeichnisstruktur und Konfiguration anlegen WAHA wird zentral in einem eigenen Verzeichnis unter `/opt/waha` betrieben. Dort liegen später sowohl die Docker-Compose-Datei als auch Konfiguration, Logs und persistente Daten. So bleibt das System klar strukturiert und leicht sicherbar. Erstelle zunächst das Hauptverzeichnis und wechsle hinein: ```bash mkdir -p /opt/waha cd /opt/waha ``` Lege anschließend die Unterordner für Konfiguration, Logs und Daten an: ```bash mkdir -p config logs data ``` 👉 **Screenshot geeignet:** Terminal mit ausgeführtem `ls -l /opt/waha` (alle drei Unterordner sichtbar) Nun folgt die grundlegende **`.env`-Datei**, in der alle wichtigen Parameter definiert sind. Öffne sie im Editor: ```bash nano /opt/waha/.env ``` Füge folgenden Inhalt ein: ``` # Basis-Konfiguration TZ=Europe/Berlin WAHA_PORT=3000 WAHA_DATA_PATH=/opt/waha/data # Sicherheit WAHA_SECRET=$(openssl rand -hex 32) # Logging WAHA_LOG_LEVEL=info # Admin-Zugang (optional) WAHA_ADMIN_USER=admin WAHA_ADMIN_PASSWORD=changeMe123! ``` Speichern (STRG + O, Enter) und schließen (STRG + X). > [!NOTE] > Die Datei `.env` wird von Docker Compose automatisch eingelesen. > Sie enthält sensible Daten wie Passwörter und Schlüssel – daher sollten die Berechtigungen auf root beschränkt bleiben. 👉 **Screenshot geeignet:** geöffnete `.env`-Datei mit markierten Variablen (Port, Log-Level, Admin-Zugang) Jetzt folgt die eigentliche **`docker-compose.yml`**-Datei. Sie definiert den WAHA-Dienst und die dazugehörigen Volumes. ```bash nano /opt/waha/docker-compose.yml ``` Füge folgenden Inhalt ein: ```yaml version: "3.9" services: waha: image: devlikeapro/whatsapp-http-api:latest container_name: waha restart: unless-stopped env_file: - .env ports: - "3000:3000" volumes: - ./data:/app/data - ./config:/app/config - ./logs:/app/logs ``` Speichern und schließen. > [!TIP] > Diese Struktur entspricht der aktuellen offiziellen Empfehlung des WAHA-Projekts. > Alle Daten liegen lokal, Updates erfolgen über Image-Pulls, und ein Neustart setzt die laufende Session nicht zurück, > solange der `/opt/waha/data`-Ordner erhalten bleibt. 👉 **Screenshot geeignet:** Terminalansicht mit geöffneter `docker-compose.yml` und markiertem Dienst `waha` ### Schritt 4 – Container starten und erste Verbindung prüfen Mit der vorbereiteten `.env`- und `docker-compose.yml`-Datei kannst du WAHA jetzt starten. Alle erforderlichen Komponenten werden automatisch geladen und im Hintergrund ausgeführt. Starte den Dienst mit: ```bash docker compose up -d ``` Während des ersten Starts lädt Docker das WAHA-Image von **devlikeapro/whatsapp-http-api** herunter und initialisiert die Datenstruktur im Ordner `/opt/waha/data`. Überprüfe anschließend den Status: ```bash docker compose ps ``` Die Ausgabe sollte in etwa so aussehen: ``` NAME IMAGE STATUS PORTS waha devlikeapro/whatsapp-http-api:latest Up 1 minute 0.0.0.0:3000->3000/tcp ``` 👉 **Screenshot geeignet:** Terminalausgabe von `docker compose ps` mit aktivem Container *Up* Wenn der Container läuft, öffne im Browser: ``` http://:3000 ``` Du solltest die WAHA-Weboberfläche sehen. Beim ersten Start wird dir ein **QR-Code** angezeigt, über den du dein WhatsApp-Konto mit der Instanz verbindest. > [!NOTE] > Dieser QR-Code muss mit der WhatsApp-App auf deinem Smartphone gescannt werden – genauso wie bei WhatsApp Web. > Nach erfolgreicher Kopplung bleibt die Session aktiv, solange der Container läuft und die Daten erhalten bleiben. 👉 **Screenshot geeignet:** Browseransicht mit WAHA-QR-Code zur WhatsApp-Verknüpfung Wenn du den QR-Code gescannt hast, sollte in der WAHA-Weboberfläche der Status **„Connected“** erscheinen. Damit ist die Verbindung zwischen deinem WhatsApp-Konto und dem UCC erfolgreich hergestellt. Prüfe den Status auch über die API: ```bash curl http://localhost:3000/api/sessions ``` Die Ausgabe sollte bestätigen, dass eine aktive Session existiert. > [!TIP] > Wenn der QR-Code nicht erscheint oder sich die Seite nach dem Scannen nicht aktualisiert, > überprüfe die Browserkonsole und Containerlogs: > ```bash > docker compose logs -f waha > ``` > In den meisten Fällen liegt die Ursache an einer blockierten WebSocket-Verbindung oder einem temporären Timeout beim Start. 👉 **Screenshot geeignet:** Browserfenster mit WAHA-Status „Connected“ und sichtbarer API-URL ### Schritt 5 – Integration in Nginx Proxy Manager (NPM) Damit WAHA sicher und bequem erreichbar ist, wird der interne Port **3000** jetzt über den **Nginx Proxy Manager** veröffentlicht. So erhältst du eine verschlüsselte HTTPS-Verbindung und kannst die API später direkt aus n8n oder anderen Diensten ansprechen. #### Proxy-Host anlegen 1. Öffne das Dashboard des **Nginx Proxy Manager**. 2. Klicke auf **Add Proxy Host**. 3. Trage folgende Werte ein: | Feld | Wert | |------|------| | **Domain Names** | `waha.deinedomain.tld` | | **Scheme** | `http` | | **Forward Hostname / IP** | `` | | **Forward Port** | `3000` | | **Block Common Exploits** | aktivieren | | **Websockets Support** | aktivieren | Wechsle anschließend in den Reiter **SSL** und aktiviere: - **Request a new SSL Certificate** - **Force SSL** - **HTTP/2 Support** - **HSTS Enabled** Klicke danach auf **Save**. > [!NOTE] > Der Proxy Manager erzeugt automatisch ein gültiges Let’s-Encrypt-Zertifikat. > Achte darauf, dass die Domain bereits korrekt auf deinen Server zeigt – sonst schlägt die Zertifikatsprüfung fehl. 👉 **Screenshot geeignet:** NPM-Dashboard mit geöffnetem Proxy-Host `waha.deinedomain.tld` #### Verbindung prüfen Öffne im Browser: ``` https://waha.deinedomain.tld ``` Wenn alles funktioniert, siehst du erneut das WAHA-Webinterface – diesmal über eine gesicherte HTTPS-Verbindung. Das **Schloss-Symbol** im Browser bestätigt das aktive SSL-Zertifikat. > [!TIP] > Sollte der Browser keine Verbindung herstellen, überprüfe im NPM-Dashboard IP-Adresse und Port. > In vielen Fällen hilft ein einfacher Neustart des Containers: > ```bash > docker compose restart > ``` 👉 **Screenshot geeignet:** Browserfenster mit WAHA-Interface unter `https://waha.deinedomain.tld` (Schloss-Symbol sichtbar) ### Schritt 6 – Erste API-Tests und Nachrichten senden Nach erfolgreicher Verbindung kannst du jetzt prüfen, ob die API korrekt arbeitet und Nachrichten über dein WhatsApp-Konto gesendet werden können. WAHA stellt dafür eine einfache HTTP-Schnittstelle bereit, die direkt getestet werden kann. #### Verbindung prüfen Zuerst prüfen wir, ob die Session korrekt verbunden ist: ```bash curl https://waha.deinedomain.tld/api/sessions ``` Die Ausgabe sollte in etwa so aussehen: ```json [ { "name": "default", "status": "connected", "owner": "+491701234567", "platform": "android", "createdAt": "2025-10-19T17:00:00.000Z" } ] ``` > [!NOTE] > Wenn der Status „disconnected“ oder „pairing“ lautet, wurde die Verbindung unterbrochen. > In diesem Fall muss der QR-Code neu gescannt werden. > WAHA zeigt diesen automatisch an, wenn du die Weboberfläche erneut öffnest. 👉 **Screenshot geeignet:** Terminalausgabe von `curl /api/sessions` mit sichtbarem Status *connected* #### Testnachricht senden Nun kannst du eine einfache Textnachricht verschicken. Ersetze im folgenden Beispiel die Telefonnummer durch eine reale WhatsApp-Nummer (mit internationaler Ländervorwahl, **ohne Pluszeichen oder Leerzeichen**): ```bash curl -X POST https://waha.deinedomain.tld/api/sendText \ -H "Content-Type: application/json" \ -d '{ "chatId": "491701234567@c.us", "text": "Testnachricht aus dem UCC – gesendet über WAHA 🦉" }' ``` Wenn alles korrekt eingerichtet ist, erhält das Zielgerät die Nachricht innerhalb weniger Sekunden. > [!TIP] > Verwende für interne Tests eine eigene Nummer oder ein separates Gerät. > So verhinderst du, dass der Hauptaccount bei ungewöhnlichen Automatisierungen gesperrt wird. > WhatsApp erkennt zu häufige automatisierte Aktionen und kann den Account temporär blockieren. 👉 **Screenshot geeignet:** WhatsApp-Chatfenster auf Smartphone mit empfangener Testnachricht „Testnachricht aus dem UCC – gesendet über WAHA 🦉“ #### Nachrichten empfangen Eingehende Nachrichten werden standardmäßig per Webhook weitergegeben. Diese Funktion nutzt du später für die Integration mit n8n. Um zu prüfen, ob eingehende Nachrichten erkannt werden, rufe die API-Events ab: ```bash curl https://waha.deinedomain.tld/api/messages ``` Du erhältst eine Liste der zuletzt empfangenen Nachrichten. > [!NOTE] > Wenn keine Nachrichten erscheinen, prüfe die Containerlogs: > ```bash > docker compose logs -f waha > ``` > Eine stabile Internetverbindung des Smartphones ist zwingend erforderlich, > da WAHA auf WhatsApp Web basiert und eine permanente Synchronisation erwartet. 👉 **Screenshot geeignet:** Terminalausgabe mit empfangener JSON-Nachricht unter `/api/messages` ### Schritt 7 – Dauerbetrieb und Neustart-Verhalten prüfen Damit WAHA nach einem Neustart des Containers oder Hosts automatisch wieder verfügbar ist, prüfst du jetzt das Neustart-Verhalten und sicherst die Session-Daten dauerhaft ab. Zuerst prüfen, ob in der `docker-compose.yml` der Neustart-Modus korrekt gesetzt ist: ```bash grep restart /opt/waha/docker-compose.yml ``` Die Ausgabe sollte enthalten: ``` restart: unless-stopped ``` > [!NOTE] > Dieses Flag sorgt dafür, dass der Container automatisch wieder startet, > sobald Docker nach einem Reboot oder Fehler neu hochfährt. > Ein zusätzlicher systemd-Dienst ist nicht erforderlich. 👉 **Screenshot geeignet:** Terminalausgabe mit sichtbarem Eintrag `restart: unless-stopped` Führe jetzt einen kontrollierten Neustart des Containers durch: ```bash reboot ``` Nach dem Reboot erneut einloggen und prüfen, ob der Dienst automatisch gestartet wurde: ```bash docker compose ps ``` Die Ausgabe sollte wieder den Status **Up** anzeigen. > [!TIP] > Wenn der Container nicht automatisch startet, überprüfe, ob Docker Compose beim Systemstart aktiviert ist. > Der folgende Befehl zeigt den Status: > ```bash > systemctl status docker > ``` > Docker sollte aktiv („active (running)“) sein. 👉 **Screenshot geeignet:** Terminalausgabe von `docker compose ps` nach Neustart (Containerstatus *Up*) Prüfe anschließend, ob die WhatsApp-Session erhalten geblieben ist: ```bash curl https://waha.deinedomain.tld/api/sessions ``` Die Session sollte weiterhin als **connected** angezeigt werden. Falls der Status „pairing“ oder „disconnected“ erscheint, wurde die Session im RAM statt auf der Festplatte gespeichert. > [!IMPORTANT] > WAHA speichert Sitzungsdaten im Volume `/opt/waha/data`. > Stelle sicher, dass dieser Ordner persistent gemountet ist. > Nur so bleibt die Kopplung nach einem Neustart erhalten. 👉 **Screenshot geeignet:** Browseransicht WAHA-Interface nach Neustart mit Statusanzeige *Connected* Damit ist der Dauerbetrieb von WAHA gewährleistet. Der Container startet automatisch, hält die Verbindung dauerhaft aktiv und bleibt über die Proxy-Domain `https://waha.deinedomain.tld` sicher erreichbar.