Thomas/Homelab--Bratonein-Kontrollzentrum--Tutorial

Files

Thomas Dannenberg 92e1b6ea9a Kapitel 19/Free Rohtext.md aktualisiert

2025-10-22 20:37:02 +00:00

40 KiB

Raw Blame History

Kapitel 19 – 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:
```
ssh root@<IP-des-Containers>
```
Ersetze <IP-des-Containers> 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:

apt update && apt upgrade -y

Nach Abschluss den Container neu starten:

reboot

Anschließend erneut per SSH anmelden:

ssh root@<IP-des-Containers>

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.

apt install -y ca-certificates curl gnupg lsb-release

Nun wird das offizielle Docker-Repository hinzugefügt und die aktuelle Engine installiert:

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:

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:

mkdir -p /opt/waha
cd /opt/waha

Lege anschließend die Unterordner für Konfiguration, Logs und Daten an:

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:

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.

nano /opt/waha/docker-compose.yml

Füge folgenden Inhalt ein:

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:

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:

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://<IP-des-Containers>: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:

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:
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

Öffne das Dashboard des Nginx Proxy Manager.
Klicke auf Add Proxy Host.
Trage folgende Werte ein:

Feld	Wert
Domain Names	`waha.deinedomain.tld`
Scheme	`http`
Forward Hostname / IP	`<IP-des-WAHA-Containers>`
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:
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:

curl https://waha.deinedomain.tld/api/sessions

Die Ausgabe sollte in etwa so aussehen:

[
  {
    "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):

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:

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:
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:

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:

reboot

Nach dem Reboot erneut einloggen und prüfen, ob der Dienst automatisch gestartet wurde:

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:
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:

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.

Schritt 8 – Automatische WhatsApp-Benachrichtigung beim Streamstart

In diesem Schritt kombinierst du n8n und WAHA, um beim Start deines Streams automatisch eine WhatsApp-Nachricht an deine Community oder dein Team zu senden.
Damit wird WAHA aktiv eingesetzt und zeigt, wie sich dein UCC mit Streaming-Ereignissen verbinden lässt.

👉 Screenshot geeignet: n8n-Dashboard mit Workflow „Streamstart → WAHA Nachricht senden“

Ziel des Workflows

Sobald dein Stream (z. B. auf Twitch) live geht, löst n8n den Workflow aus und sendet über die WAHA-API eine WhatsApp-Nachricht in eine definierte Gruppe oder an einen Einzelkontakt.
Beispielnachricht:

„🎬 Der Stream ist live! Schau jetzt rein auf twitch.tv/Bratonien_TV ✨“

Voraussetzungen

n8n ist eingerichtet, läuft stabil und ist über HTTPS erreichbar.
WAHA ist verbunden, über https://waha.deinedomain.tld erreichbar und mit deinem WhatsApp-Konto gekoppelt.
Du hast eine WhatsApp-Gruppe oder einen Kontakt, den dein Account direkt anschreiben darf.
Der Twitch-Trigger (Community-Node) ist installiert. Siehe im n8n-Kapitel den Abschnitt „Wichtige Community-Nodes“.
Falls der Node fehlt, installiere ihn in n8n: Settings → Community Nodes → Install → @n8n-nodes/twitch.

👉 Screenshot geeignet: WAHA-Oberfläche mit Status Connected und sichtbarer WhatsApp-Nummer

Workflow in n8n erstellen

Öffne dein n8n-Dashboard und erstelle einen neuen Workflow mit zwei Nodes:
Node 1 – Twitch Trigger und Node 2 – HTTP Request → WAHA Nachricht senden.
Verbinde die Nodes linear – sobald der Stream startet, sendet WAHA die Nachricht.

Node 1 – Twitch Trigger

Zweck: Erkennt, wenn dein Twitch-Kanal live geht, und startet den Workflow.

Node-Typ: Twitch Trigger
Name: Stream Start
Parameter:

Event: Stream started
Channel Name: <dein_Twitch_Kanalname>
Authentication: OAuth 2 (Twitch-Account)

Note

Der Twitch-Trigger ist ein Community-Node und muss installiert/aktiviert sein.
Er überwacht die Twitch-API in Intervallen und triggert den Workflow automatisch, sobald dein Kanal live ist.

👉 Screenshot geeignet: geöffneter Node „Twitch Trigger“ mit Event Stream started und aktivem OAuth-Token

Node 2 – HTTP Request → WAHA Nachricht senden

Zweck: Sendet über die WAHA-API eine vorbereitete Nachricht an eine definierte WhatsApp-Chat-ID.

Node-Typ: HTTP Request
Name: WAHA – Streambenachrichtigung
Parameter:

Method: POST

URL:

https://waha.deinedomain.tld/api/sendText

Header Parameter:
- Content-Type: application/json

Body Parameter:

{
  "chatId": "49XXXXXXXXXXX@c.us",
  "text": "🎬 Der Stream ist live! Schau jetzt rein auf twitch.tv/Bratonien_TV ✨"
}

Chat-ID ermitteln

Damit WAHA weiß, wohin die Nachricht gesendet werden soll, benötigst du die Chat-ID des Zielkontakts oder der WhatsApp-Gruppe.
Die ID wird automatisch generiert, sobald du mit dieser Person oder Gruppe mindestens einmal über WAHA interagiert hast.

Öffne die WAHA-Weboberfläche (https://waha.deinedomain.tld).
Scanne den QR-Code, falls noch nicht verbunden, und öffne WhatsApp auf deinem Smartphone.
Sende von deinem WhatsApp-Konto eine Nachricht an dich selbst oder an die gewünschte Gruppe (z. B. „Test“).
Gehe in WAHA auf den Reiter Logs oder öffne die API im Browser:
```
https://waha.deinedomain.tld/api/messages
```
Suche in der Ausgabe nach chatId.
Typische Formate sind:
- Einzelchat: 49XXXXXXXXXXX@c.us
- Gruppe: 1234567890-987654321@g.us

Diese ID kopierst du exakt (inklusive Suffix @c.us oder @g.us) in das Feld chatId deines HTTP Request-Nodes.

Tip

Bei Gruppen-ID empfiehlt es sich, eine Testnachricht in die Gruppe zu schicken und dann direkt die ID aus der API-Antwort zu übernehmen.
Achte auf die korrekte Schreibweise – bereits ein falsches Zeichen führt zu einem 404- oder 400-Fehler.

👉 Screenshot geeignet: WAHA-Log oder API-Ausgabe mit markiertem chatId-Eintrag (Beispiel: 49XXXXXXXXXXX@c.us)

Verbindung zwischen den Nodes

Verbinde Node 1 (Twitch Trigger) mit Node 2 (WAHA Nachricht senden) über den Main-Output.
Sobald der Stream startet, führt n8n automatisch den HTTP-Request aus und WAHA sendet die Nachricht.

👉 Screenshot geeignet: n8n-Canvas mit verbundener Kette „Twitch Trigger → WAHA Nachricht senden“

Testlauf

Öffne die WAHA-Weboberfläche (https://waha.deinedomain.tld) und prüfe den Status Connected.
Starte auf Twitch testweise einen Stream (z. B. über OBS).
n8n erkennt den Streamstart und führt den HTTP-Request aus.
Innerhalb weniger Sekunden erscheint die WhatsApp-Nachricht in deiner Testgruppe oder bei deinem Kontakt.

👉 Screenshot geeignet: WhatsApp-Chat mit eingegangener Nachricht „Der Stream ist live! Schau jetzt rein…“

Note

Dieser Workflow nutzt nur das Senden via WAHA. Er vermeidet automatisierte Antworten auf eingehende Nachrichten und bleibt damit näher an den WhatsApp-Richtlinien.
Verwende ausschließlich eigene Gruppen oder interne Chats; WhatsApp kann übermäßige Automation als Missbrauch einstufen.

Anpassungsmöglichkeiten

Dynamischer Nachrichtentext:

"text": "🎥 Live: {{$json[\"title\"]}} – schau jetzt vorbei!"

Mehrere Plattformen:
Ergänze weitere Trigger (z. B. YouTube Live) und leite alle auf denselben WAHA-Send-Node.
Fallback:
Falls WAHA nicht erreichbar ist, kann n8n alternativ eine Discord-Nachricht oder E-Mail senden.

👉 Screenshot geeignet: geöffneter Node „WAHA Nachricht senden“ mit markiertem JSON-Body und Variablenfeld

Troubleshooting & Tipps

Auch wenn WAHA grundsätzlich stabil arbeitet, kann es in der Kombination mit n8n und Twitch-Triggern zu Verbindungs- oder Authentifizierungsproblemen kommen.
Die folgenden Punkte helfen, typische Fehler schnell zu erkennen und dauerhaft zu vermeiden.

Verbindung zu WAHA unterbrochen

Symptom:
In n8n erscheint der Fehler ECONNREFUSED oder Request failed with status 502.
In der Weboberfläche steht WAHA auf Disconnected.

Ursachen & Lösungen:

Sitzung abgelaufen:
WhatsApp verlangt, dass das verknüpfte Hauptgerät mindestens alle 14 Tage online ist.
Öffne WhatsApp auf dem Handy und prüfe, ob der gekoppelte Web-Client aktiv bleibt.
Scanne bei Bedarf den QR-Code in der WAHA-Weboberfläche erneut.
Container neu gestartet ohne persistente Daten:
Wenn das Volume /opt/waha/data nicht dauerhaft eingebunden ist, verliert WAHA beim Neustart seine Sitzung.
Prüfe in Proxmox oder in der pct config, ob das Datenverzeichnis korrekt gemountet ist.
Proxy oder Zertifikatfehler:
Wenn WAHA über den Nginx Proxy Manager eingebunden ist, prüfe das Zertifikat und die Weiterleitung.
Fehlerhafte HTTPS-Konfigurationen führen oft zu 502-Antworten in n8n.

👉 Screenshot geeignet: WAHA-Weboberfläche mit Status Disconnected und QR-Code-Anzeige

n8n sendet keine Nachricht

Symptom:
Der Workflow läuft durch, aber in WhatsApp erscheint keine Nachricht.

Ursachen & Lösungen:

Falsche Chat-ID:
Prüfe im WAHA-Log oder in der API-Ausgabe, ob die Chat-ID korrekt ist (@c.us für Einzelchat, @g.us für Gruppen).
Bereits ein fehlendes Zeichen führt zu HTTP 400-Fehlern.
WAHA nicht erreichbar:
Wenn WAHA über HTTPS läuft, aber das Zertifikat abgelaufen oder falsch ausgestellt ist,
blockiert n8n den Request. Teste mit curl -k https://waha.deinedomain.tld/api/status.
HTTP-Node nicht auf JSON gesetzt:
Der Body-Type des HTTP-Requests muss application/json sein.
Andernfalls interpretiert WAHA die Daten als leer und sendet nichts.

👉 Screenshot geeignet: n8n-Log mit fehlgeschlagenem HTTP-Request und sichtbarem Fehlercode

Twitch-Trigger reagiert nicht

Symptom:
Der Workflow startet nicht, obwohl der Stream online ist.

Ursachen & Lösungen:

Node nicht installiert oder deaktiviert:
Prüfe unter Settings → Community Nodes, ob der Twitch-Trigger aktiviert ist.
Falls nicht, installiere ihn wie im n8n-Kapitel beschrieben.
OAuth abgelaufen:
In den Node-Details steht „Invalid credentials“.
Öffne die Authentifizierung erneut, melde dich mit Twitch an und speichere die Verbindung.
Rate-Limit erreicht:
Die Twitch-API erlaubt nur eine begrenzte Anzahl an Abfragen pro Stunde.
Wenn du mehrere Workflows mit demselben Account nutzt, plane die Trigger-Intervalle zeitversetzt.

👉 Screenshot geeignet: n8n-Node „Twitch Trigger“ mit sichtbarer Fehlermeldung „Invalid credentials“

Allgemeine Stabilität

Empfehlungen:

WAHA regelmäßig neu starten:
Ein Neustart einmal pro Woche verhindert Sitzungsfehler durch veraltete Tokens.
```
systemctl restart waha
```
Logs aktiv prüfen:
WAHA protokolliert alle API-Zugriffe in /opt/waha/logs/.
Prüfe dort auf wiederholte 401- oder 403-Fehler – sie weisen auf Authentifizierungsprobleme hin.
Ressourcen beobachten:
Wenn die OCR- oder KI-Komponenten parallel laufen, kann die CPU-Last ansteigen.
Überwache den Container mit htop oder Netdata und erhöhe bei Bedarf die CPU-Zuteilung.

👉 Screenshot geeignet: Terminalausgabe von systemctl status waha mit aktivem Dienststatus

Tip

Halte die Containerumgebung möglichst statisch.
WAHA arbeitet am zuverlässigsten, wenn IP, Hostname und Mountpfade unverändert bleiben.
Vermeide Neustarts während laufender Streams oder Workflows.

Fehlermeldung „Invalid session“ oder „pairing required“

Symptom:
WAHA meldet „Invalid session“ oder zeigt in der Weboberfläche erneut den QR-Code an.

Ursachen & Lösungen:

Sitzung durch WhatsApp zurückgesetzt:
Wenn du dein WhatsApp-Konto auf dem Smartphone abmeldest oder neu installierst, werden alle aktiven Web-Sitzungen ungültig.
Lösung: In WAHA auf Reconnect klicken und den QR-Code erneut mit WhatsApp scannen.
Gerätewechsel oder Backup-Wiederherstellung:
Nach einem Gerätewechsel (z. B. neues Smartphone) verliert WhatsApp alle Web-Verbindungen.
In diesem Fall muss die Kopplung in WAHA komplett neu hergestellt werden.
Zugriff über mehrere Instanzen:
Wenn du dasselbe Konto parallel in zwei WAHA-Instanzen nutzt, kommt es zu Session-Konflikten.
Nur eine aktive Verbindung pro Konto ist möglich.

👉 Screenshot geeignet: WAHA-Weboberfläche mit QR-Code und Meldung pairing required

API-Antworten mit Fehlercode 401 oder 403

Symptom:
Der HTTP-Request in n8n schlägt fehl, und im Log erscheint 401 Unauthorized oder 403 Forbidden.

Ursachen & Lösungen:

Falscher API-Endpunkt:
Achte auf die exakte URL. Sie muss mit /api/sendText enden und per HTTPS erreichbar sein.
Tipp: curl -k https://waha.deinedomain.tld/api/status sollte eine JSON-Antwort liefern.
Authentifizierung deaktiviert:
Wenn du in WAHA Authentifizierung aktiviert hast, muss n8n im Header den Token mitsenden:
```
Authorization: Bearer <DEIN_API_TOKEN>
```
Den Token legst du in WAHA unter Settings → API Tokens an.
CORS- oder Proxy-Fehler:
Wenn n8n über HTTPS läuft, WAHA aber per HTTP, blockiert der Browser Cross-Origin-Requests.
Beide Systeme sollten über HTTPS erreichbar sein, idealerweise mit gültigen Zertifikaten.

👉 Screenshot geeignet: n8n-HTTP-Node mit sichtbarem Fehlercode 401 im Ausgabefeld

Wiederholte Timeouts oder keine Antwort

Symptom:
Der Request läuft durch, aber n8n zeigt „timeout after 60000ms“.

Ursachen & Lösungen:

Container ausgelastet:
Wenn mehrere OCR- oder KI-Container gleichzeitig laufen, kann der WAHA-Prozess blockiert werden.
Beobachte mit htop, ob CPU oder RAM ausgelastet sind.
DNS-Auflösung fehlerhaft:
n8n erreicht waha.deinedomain.tld nicht, weil Pi-hole oder Unbound Anfragen blockieren.
Teste innerhalb des n8n-Containers:
```
curl -v https://waha.deinedomain.tld/api/status
```
Zu kurze Timeout-Zeit:
Setze im HTTP-Request-Node unter Options → Timeout einen höheren Wert, z. B. 120000 (2 Minuten).

👉 Screenshot geeignet: n8n-Log mit Timeout-Eintrag im Workflow-Ausführungsfenster

Sicherheit und Schutz vor Sperrung

Empfehlungen:

Keine Massenversendungen:
WhatsApp erkennt zu häufige automatisierte Nachrichten als Spam.
Sende nur seltene, manuell ausgelöste oder durch Events getriggerte Nachrichten.
Business-Konto verwenden:
Für produktive Kommunikation empfiehlt sich ein WhatsApp Business-Konto,
da private Konten durch Automatisierung eher gesperrt werden können.
Regelmäßige Backups:
Sichere /opt/waha/data regelmäßig per Kopia oder rsync, damit Sitzungen und Logs erhalten bleiben.
Trennung von Test- und Produktiv-Instanzen:
Teste neue Workflows in einer separaten WAHA-Instanz, um dein Hauptkonto zu schützen.

👉 Screenshot geeignet: WAHA-Einstellungen mit aktivem WhatsApp-Business-Account

Tip

Vermeide Intervall-Trigger mit hoher Frequenz.
Eine Abfrage alle 10 – 15 Minuten genügt, um Stream- oder Statusänderungen zu erkennen, ohne die API zu überlasten.

Logs und Fehlersuche im Detail

Wenn ein Workflow nicht wie erwartet funktioniert, liefern die Logs von WAHA und n8n meist alle nötigen Hinweise.
Durch gezieltes Prüfen lässt sich schnell feststellen, ob der Fehler auf der Seite von WhatsApp, WAHA oder n8n liegt.

WAHA-Logs prüfen:

tail -f /opt/waha/logs/app.log

Die Datei enthält alle eingehenden und ausgehenden Requests.
Achte auf Einträge mit "sendText" und "statusCode".
Ein erfolgreicher Versand endet mit "statusCode":200.

Tip

Wenn keine Einträge erscheinen, erreicht der Request aus n8n den WAHA-Container gar nicht.
In diesem Fall stimmt entweder die URL nicht oder der Reverse Proxy blockiert die Verbindung.

n8n-Logs prüfen:

docker logs -f n8n

oder bei LXC-Installation:

journalctl -u n8n -f

Hier sind insbesondere Fehlermeldungen wie ECONNRESET, ENOTFOUND oder ETIMEDOUT relevant – sie deuten auf Verbindungsprobleme hin.

👉 Screenshot geeignet: Terminal mit tail -f /opt/waha/logs/app.log und sichtbarer API-Antwort statusCode:200

Neustart und Wiederherstellung

Falls WAHA nicht mehr reagiert oder der Status dauerhaft Disconnected bleibt, kann ein sauberer Neustart helfen.
Dabei darf das Sitzungs-Volume nicht gelöscht werden, sonst ist die Kopplung verloren.

Empfohlener Neustart:

systemctl stop waha
sleep 3
systemctl start waha

Container neu starten (Proxmox):

pct restart <CTID>

Wenn nach dem Neustart wieder der QR-Code angezeigt wird, war das Volume /opt/waha/data nicht persistent eingebunden.
Passe die Mounts im Proxmox-GUI oder in der pct config an, um dauerhafte Speicherung sicherzustellen.

👉 Screenshot geeignet: Proxmox-Konsole mit pct restart und erfolgreichem Reconnect in der WAHA-Oberfläche

Netzwerk- und Portprobleme

Symptom:
n8n kann WAHA über https://waha.deinedomain.tld nicht erreichen.

Lösungsansätze:

Proxy-Fehler:
Prüfe im Nginx Proxy Manager, ob Port 3000 (Standardport von WAHA) korrekt weitergeleitet wird.
Bei aktivem SSL muss „Websockets Support“ eingeschaltet sein.
Firewall:
Stelle sicher, dass interne Firewalls oder iptables-Regeln den Zugriff zwischen den Containern erlauben.
DNS-Auflösung:
Wenn interne Domains verwendet werden, kontrolliere Pi-hole oder Unbound.
Teste den Hostname direkt aus dem n8n-Container:
```
ping waha.deinedomain.tld
```

👉 Screenshot geeignet: Nginx Proxy Manager-Proxy-Host mit aktivierter Websocket-Option

Fehlerhafte API-Aufrufe erkennen

Wenn die API in WAHA falsche oder unvollständige Requests erhält, werden sie im Log mit "statusCode":400 oder "Invalid parameters" protokolliert.

Typische Ursachen:

Der Body enthält ungültige JSON-Syntax.
chatId oder text fehlen.
Der Content-Type wurde nicht korrekt auf application/json gesetzt.

Prüfung mit curl:

curl -X POST https://waha.deinedomain.tld/api/sendText \
  -H "Content-Type: application/json" \
  -d '{"chatId": "49XXXXXXXXXXX@c.us", "text": "Testnachricht"}'

Wenn die Antwort { "success": true } lautet, funktioniert die API korrekt.

👉 Screenshot geeignet: Terminalausgabe erfolgreicher curl-Test mit success: true

Typische Ursachen für instabile Automatisierungen

Nicht persistente Tokens:
Wenn n8n beim Neustart die OAuth-Verbindungen zu Twitch oder WAHA verliert, speichere sie in Vaultwarden und binde sie als Umgebungsvariablen ein.
Zeitliche Überschneidung:
Läuft der Workflow zu oft (z. B. durch fehlerhaften Twitch-Trigger), sperrt Twitch API-Requests temporär.
Nicht synchronisierte Systemzeiten:
Prüfe, ob beide LXC-Container (n8n und WAHA) dieselbe Zeitzone und NTP-Synchronisation verwenden:
```
timedatectl
```

👉 Screenshot geeignet: Ausgabe timedatectl mit synchronisierter Systemzeit

Tip

Wenn du WAHA und n8n auf unterschiedlichen Hosts betreibst, verwende nach Möglichkeit interne DNS-Namen statt öffentlicher Domains.
Das vermeidet SSL-Handshake-Fehler und verkürzt Latenzzeiten bei automatisierten Workflows.

Nachricht kommt an, aber ohne Text oder mit fehlerhaften Sonderzeichen

Symptom:
Die WhatsApp-Nachricht wird gesendet, erscheint auf dem Empfängergerät aber leer oder enthält fehlerhafte Umlaute und Sonderzeichen.

Ursachen & Lösungen:

Zeichensatzfehler im Request:
n8n sendet den Text standardmäßig im UTF-8-Format, aber wenn Sonderzeichen nicht richtig escaped werden, verwirft WhatsApp sie teilweise.
Achte darauf, dass das Textfeld im HTTP-Request-Node korrekt maskiert ist:
```
{"text": "Hallo! Vielen Dank für deine Nachricht. 😊"}
```
und nicht als einfacher String ohne Anführungszeichen.
Markdown- oder Steuerzeichen im Text:
Entferne Zeilenumbrüche, Anführungszeichen oder unsichtbare Formatierungszeichen, die aus Copy-&-Paste stammen können.
Problem bei Emojis oder Symbolen:
Wenn Emojis nicht dargestellt werden, prüfe, ob dein Container locale-Unterstützung hat:
```
locale
```
Sollte LANG oder UTF-8 fehlen, installiere sie nach:
```
apt install locales && dpkg-reconfigure locales
```

👉 Screenshot geeignet: WhatsApp-Chat mit empfangener Nachricht ohne Textinhalt und markiertem fehlerhaften Emoji

Workflow ausgeführt, aber als „Fehlgeschlagen“ markiert

Symptom:
Die Nachricht wurde korrekt versendet, n8n zeigt in der Ausführung jedoch den Status Failed oder Error an.

Ursachen & Lösungen:

WAHA liefert keine korrekte JSON-Antwort:
Einige WAHA-Versionen antworten nur mit true oder leerem Body, was n8n als Fehler interpretiert.
Setze im HTTP-Request-Node unter Options → Ignore Response Code den Haken auf true,
damit der Workflow auch bei leeren Antworten als erfolgreich gilt.
Falscher Erfolgscode:
Manche Instanzen geben 201 oder 204 zurück statt 200.
Passe in den Node-Einstellungen unter Continue On Fail die Behandlung entsprechend an.
n8n-Retry aktiv:
Wenn der Node mehrfach neu ausgeführt wird, kann das Logging einen Fehlerstatus behalten,
obwohl die Nachricht bereits verschickt wurde.

👉 Screenshot geeignet: n8n-Execution-Log mit Status Failed trotz erfolgreich gesendeter WhatsApp-Nachricht

Tip

Prüfe in solchen Fällen immer zuerst den tatsächlichen Chatverlauf.
Wenn die Nachricht angekommen ist, kann der „Fehler“ meist ignoriert werden oder durch Anpassung der Response-Einstellungen dauerhaft vermieden werden.

Ergebnis

Nach Abschluss dieses Kapitels läuft in deinem UCC ein vollständig funktionsfähiges System für automatisierte WhatsApp-Nachrichten.
WAHA übernimmt die Verbindung zu WhatsApp, während n8n die Logik und Steuerung bereitstellt.
Beide Komponenten sind fest in deine bestehende Infrastruktur integriert und arbeiten stabil über den Nginx Proxy Manager.

Dein aktuelles Setup umfasst:

WAHA-Container – simuliert das WhatsApp-Webinterface und stellt eine lokale API bereit
n8n-Container – erstellt und steuert Workflows, die Nachrichten automatisch auslösen
Nginx Proxy Manager – sorgt für sicheren HTTPS-Zugriff
Persistente Datenspeicherung unter /opt/waha/data – Sitzungen bleiben erhalten
Funktionierende Integration mit Twitch (Community Node) als Beispiel für Event-gesteuerte Automatisierung

👉 Screenshot geeignet: n8n-Dashboard mit aktivem Workflow und WAHA-Container im Proxmox-Interface

Damit hast du eine stabile Grundlage geschaffen, um WhatsApp in deine eigene Automatisierungsumgebung einzubinden – ohne Cloud-Abhängigkeit oder externe Dienste.
WAHA erlaubt dir, Nachrichten direkt über deine Infrastruktur zu senden und zu empfangen, vollständig unter eigener Kontrolle.

Tip

Im Premium-Kapitel bauen wir dieses System zu einem interaktiven Beispiel aus:
Ein smarter WhatsApp-Bot reagiert automatisch auf Zuschauerfragen wie
„Wann ist der nächste Stream?“ oder „Wie kann ich mitmachen?“
Dafür kombinieren wir WAHA, n8n und einen KI-Agenten zu einem intelligenten Kommunikations-Workflow,
der deinen Stream-Betrieb automatisiert unterstützt.

40 KiB Raw Blame History Unescape Escape

Kapitel 19 – WAHA (WhatsApp HTTP API)

Einleitung

Voraussetzungen & Ressourcen

Container-Ressourcen

Technische Voraussetzungen

Schritt-für-Schritt-Anleitung

Schritt 1 – Container vorbereiten und System aktualisieren

Schritt 2 – Docker installieren und vorbereiten

Schritt 3 – Verzeichnisstruktur und Konfiguration anlegen

Schritt 4 – Container starten und erste Verbindung prüfen

Schritt 5 – Integration in Nginx Proxy Manager (NPM)

Proxy-Host anlegen

Verbindung prüfen

Schritt 6 – Erste API-Tests und Nachrichten senden

Verbindung prüfen

Testnachricht senden

Nachrichten empfangen

Schritt 7 – Dauerbetrieb und Neustart-Verhalten prüfen

Schritt 8 – Automatische WhatsApp-Benachrichtigung beim Streamstart

Ziel des Workflows

Voraussetzungen

Workflow in n8n erstellen

Node 1 – Twitch Trigger

Node 2 – HTTP Request → WAHA Nachricht senden

Chat-ID ermitteln

Verbindung zwischen den Nodes

Testlauf

Anpassungsmöglichkeiten

Troubleshooting & Tipps

Verbindung zu WAHA unterbrochen

n8n sendet keine Nachricht

Twitch-Trigger reagiert nicht

Allgemeine Stabilität

Fehlermeldung „Invalid session“ oder „pairing required“

API-Antworten mit Fehlercode 401 oder 403

Wiederholte Timeouts oder keine Antwort

Sicherheit und Schutz vor Sperrung

Logs und Fehlersuche im Detail

Neustart und Wiederherstellung

Netzwerk- und Portprobleme

Fehlerhafte API-Aufrufe erkennen

Typische Ursachen für instabile Automatisierungen

Nachricht kommt an, aber ohne Text oder mit fehlerhaften Sonderzeichen

Workflow ausgeführt, aber als „Fehlgeschlagen“ markiert

Ergebnis

40 KiB

Raw Blame History