diff --git a/Kapitel 18/Free Rohtext.md b/Kapitel 18/Free Rohtext.md index 22ef3ba..0fba846 100644 --- a/Kapitel 18/Free Rohtext.md +++ b/Kapitel 18/Free Rohtext.md @@ -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:** `` +- **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 + ``` + 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 +``` + +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.