Homelab--Bratonein-Kontrollzentrum--Tutorial/Kapitel 19/Free Rohtext.md

# 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:
  ```bash
  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:

```bash
apt update && apt upgrade -y
```

Nach Abschluss den Container neu starten:

```bash
reboot
```

Anschließend erneut per SSH anmelden:

```bash
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.

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

```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** | `<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:
> ```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.

### 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:**  
  ```json
  {
    "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.

1. Öffne die WAHA-Weboberfläche (`https://waha.deinedomain.tld`).
2. Scanne den QR-Code, falls noch nicht verbunden, und öffne WhatsApp auf deinem Smartphone.  
3. Sende von deinem WhatsApp-Konto **eine Nachricht an dich selbst** oder an die gewünschte Gruppe (z. B. „Test“).  
4. Gehe in WAHA auf den Reiter **Logs** oder öffne die API im Browser:
   ```
   https://waha.deinedomain.tld/api/messages
   ```
5. 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

1. Öffne die WAHA-Weboberfläche (`https://waha.deinedomain.tld`) und prüfe den Status **Connected**.  
2. Starte auf Twitch testweise einen Stream (z. B. über OBS).  
3. n8n erkennt den Streamstart und führt den HTTP-Request aus.  
4. 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:**  
  ```json
  "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:**  
1. **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.  
2. **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.  
3. **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:**  
1. **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.  
2. **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`.  
3. **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:**  
1. **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.  
2. **OAuth abgelaufen:**  
   In den Node-Details steht „Invalid credentials“.  
   Öffne die Authentifizierung erneut, melde dich mit Twitch an und speichere die Verbindung.  
3. **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:**  
1. **WAHA regelmäßig neu starten:**  
   Ein Neustart einmal pro Woche verhindert Sitzungsfehler durch veraltete Tokens.  
   ```
   systemctl restart waha
   ```
2. **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.  
3. **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:**  
1. **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.  
2. **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.  
3. **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:**  
1. **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.  
2. **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.  
3. **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:**  
1. **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.  
2. **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
   ```  
3. **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:**  
1. **Keine Massenversendungen:**  
   WhatsApp erkennt zu häufige automatisierte Nachrichten als Spam.  
   Sende nur seltene, manuell ausgelöste oder durch Events getriggerte Nachrichten.  
2. **Business-Konto verwenden:**  
   Für produktive Kommunikation empfiehlt sich ein **WhatsApp Business-Konto**,  
   da private Konten durch Automatisierung eher gesperrt werden können.  
3. **Regelmäßige Backups:**  
   Sichere `/opt/waha/data` regelmäßig per Kopia oder rsync, damit Sitzungen und Logs erhalten bleiben.  
4. **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:**
```bash
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:**
```bash
docker logs -f n8n
```
oder bei LXC-Installation:
```bash
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:**
```bash
systemctl stop waha
sleep 3
systemctl start waha
```

**Container neu starten (Proxmox):**
```bash
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:**  
1. **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.  
2. **Firewall:**  
   Stelle sicher, dass interne Firewalls oder iptables-Regeln den Zugriff zwischen den Containern erlauben.  
3. **DNS-Auflösung:**  
   Wenn interne Domains verwendet werden, kontrolliere Pi-hole oder Unbound.  
   Teste den Hostname direkt aus dem n8n-Container:  
   ```bash
   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:**
```bash
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

1. **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.  
2. **Zeitliche Überschneidung:**  
   Läuft der Workflow zu oft (z. B. durch fehlerhaften Twitch-Trigger), sperrt Twitch API-Requests temporär.  
3. **Nicht synchronisierte Systemzeiten:**  
   Prüfe, ob beide LXC-Container (n8n und WAHA) dieselbe Zeitzone und NTP-Synchronisation verwenden:  
   ```bash
   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:**  
1. **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:
   ```bash
   {"text": "Hallo! Vielen Dank für deine Nachricht. 😊"}
   ```
   und nicht als einfacher String ohne Anführungszeichen.  
2. **Markdown- oder Steuerzeichen im Text:**  
   Entferne Zeilenumbrüche, Anführungszeichen oder unsichtbare Formatierungszeichen, die aus Copy-&-Paste stammen können.  
3. **Problem bei Emojis oder Symbolen:**  
   Wenn Emojis nicht dargestellt werden, prüfe, ob dein Container locale-Unterstützung hat:
   ```bash
   locale
   ```
   Sollte `LANG` oder `UTF-8` fehlen, installiere sie nach:
   ```bash
   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:**  
1. **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.  
2. **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.  
3. **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.