Thomas/Homelab--Bratonein-Kontrollzentrum--Tutorial
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Kapitel 18/Free Rohtext.md aktualisiert

Browse Source
This commit is contained in:
Thomas Dannenberg
2025-10-19 20:25:16 +00:00
parent 089fa41ee6
commit ce25284e33
1 changed files with 435 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

543
Kapitel 18/Free Rohtext.md
View File

@@ -523,152 +523,479 @@ 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 – Webhook und automatische Antwort einrichten
### Schritt 8 – Automatische WhatsApp-Benachrichtigung beim Streamstart
Ziel dieses Schritts ist ein vollständig funktionierender Workflow:
Wenn eine WhatsApp-Nachricht bei **WAHA** eingeht, empfängt **n8n** sie automatisch,
analysiert den Inhalt und sendet sofort eine Antwort an den Absender zurück.
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:** Übersicht WAHA → n8n → WAHA-Rückkanal
👉 **Screenshot geeignet:** n8n-Dashboard mit Workflow „Streamstart → WAHA Nachricht senden“
> [!NOTE]
> Alle hier verwendeten Nodes sind in der Community-Version von n8n enthalten.
> Für diesen Basis-Workflow wird keine externe API oder kostenpflichtige Integration benötigt.
#### 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 lege einen neuen Workflow an.
Ö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 – Webhook (Trigger)
### Node 1 – Twitch Trigger
**Zweck:**
Empfängt eingehende WhatsApp-Nachrichten direkt von WAHA als JSON-Payload.
**Zweck:** Erkennt, wenn dein Twitch-Kanal live geht, und startet den Workflow.
**Node-Typ:** Webhook
**Name:** Eingang – WhatsApp
**Parameter:**
- **HTTP Method:** POST
- **Path:** `whatsapp`
→ ergibt:
```
https://n8n.deinedomain.tld/webhook/whatsapp
```
- **Response Mode:** On Received
- **Response Code:** 200
👉 **Screenshot geeignet:** n8n-Webhook-Node mit sichtbarer URL `https://n8n.deinedomain.tld/webhook/whatsapp`
##### Node 2 – Function (Nachricht analysieren)
**Zweck:**
Extrahiert Absender und Nachrichtentext aus dem empfangenen JSON,
damit sie in der Antwort verwendet werden können.
**Node-Typ:** Function
**Name:** Nachricht analysieren
**Verbindung:**
Eingang von **Node 1 (Webhook)**
**Code:**
```javascript
return [{
chatId: $json["from"],
text: $json["text"]
}];
```
👉 **Screenshot geeignet:** Function-Node mit sichtbaren Variablen `chatId` und `text`
**Node-Typ:** Twitch Trigger
**Name:** Stream Start
**Parameter:**
- **Event:** `Stream started`
- **Channel Name:** `<dein_Twitch_Kanalname>`
- **Authentication:** OAuth 2 (Twitch-Account)
> [!NOTE]
> WAHA übergibt den Absender im Format `491701234567@c.us`.
> Diese Schreibweise wird in der Antwort unverändert benötigt.
> 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.
##### Node 3 – HTTP Request → Antwort senden
👉 **Screenshot geeignet:** geöffneter Node „Twitch Trigger“ mit Event *Stream started* und aktivem OAuth-Token
**Zweck:**
Sendet über die WAHA-API eine automatische Antwort an den Absender der eingegangenen Nachricht.
### 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:** Antwort senden → WAHA
**Verbindung:**
Eingang von **Node 2 (Function)**
**Parameter:**
- **Method:** POST
**Name:** WAHA – Streambenachrichtigung
**Parameter:**
- **Method:** `POST`
- **URL:**
```
https://waha.deinedomain.tld/api/sendText
```
- **Authentication:** keine
- **Header Parameter:**
- `Content-Type`: `application/json`
- **Body:**
- `Content-Type`: `application/json`
- **Body Parameter:**
```json
{
"chatId": "={{$json["chatId"]}}",
"text": "Hallo! Vielen Dank für deine Nachricht. Dies ist eine automatische Antwort – eine persönliche Rückmeldung folgt so schnell wie möglich."
"chatId": "49XXXXXXXXXXX@c.us",
"text": "🎬 Der Stream ist live! Schau jetzt rein auf twitch.tv/Bratonien_TV ✨"
}
```
👉 **Screenshot geeignet:** HTTP-Request-Node mit Ziel-URL `/api/sendText` und markiertem JSON-Body
#### 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]
> Du kannst den Antworttext jederzeit anpassen oder später dynamisch durch eine KI oder Datenquelle ersetzen.
> Wichtig ist, dass die Variable `chatId` exakt aus der eingehenden Nachricht übernommen wird.
> 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.
##### Node 4 – Respond to Webhook
👉 **Screenshot geeignet:** WAHA-Log oder API-Ausgabe mit markiertem `chatId`-Eintrag (Beispiel: `49XXXXXXXXXXX@c.us`)
**Zweck:**
Bestätigt gegenüber WAHA, dass die Nachricht erfolgreich verarbeitet wurde.
#### Verbindung zwischen den Nodes
**Node-Typ:** Respond to Webhook
**Name:** Bestätigung an WAHA
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.
**Verbindung:**
Eingang von **Node 1 (Webhook)**
👉 **Screenshot geeignet:** n8n-Canvas mit verbundener Kette „Twitch Trigger → WAHA Nachricht senden“
**Parameter:**
- **Response Code:** 200
- **Response Body:**
```json
{ "status": "ok" }
```
#### Testlauf
👉 **Screenshot geeignet:** Respond-Node mit Body `{ "status": "ok" }`
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.
#### Test
1. Aktiviere den Workflow (**Activate Workflow**).
2. Sende vom verbundenen WhatsApp-Gerät eine Nachricht, z. B.
```
Hallo aus dem Kontrollzentrum!
```
3. n8n zeigt das empfangene Event im Webhook-Node an.
4. Innerhalb weniger Sekunden erhältst du auf dem Handy automatisch folgende Antwort:
```
Hallo! Vielen Dank für deine Nachricht. Dies ist eine automatische Antwort – eine persönliche Rückmeldung folgt so schnell wie möglich.
```
👉 **Screenshot geeignet:** WhatsApp-Chat mit empfangener automatischer Antwort
👉 **Screenshot geeignet:** WhatsApp-Chat mit eingegangener Nachricht „Der Stream ist live! Schau jetzt rein…“
> [!NOTE]
> Wenn keine Antwort ankommt, prüfe:
> – WAHA-Container läuft und ist „connected“
> – n8n-Workflow aktiv
> – HTTPS-Zertifikate gültig
> – Logs:
> ```bash
> docker compose logs -f waha
> ```
> anzeigen
> 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.
Damit ist die erste bidirektionale Integration zwischen **WAHA** und **n8n** abgeschlossen.
Das System empfängt WhatsApp-Nachrichten automatisch und reagiert selbstständig –
die Grundlage für spätere erweiterte Automatisierungen oder KI-gesteuerte Antworten.
#### 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.