diff --git a/Kapitel 18/Premium Rohtext.md b/Kapitel 18/Premium Rohtext.md new file mode 100644 index 0000000..e6a47f1 --- /dev/null +++ b/Kapitel 18/Premium Rohtext.md @@ -0,0 +1,362 @@ +# Premium – WAHA: Automatisierte Statusmeldungen & KI-gestützte Antworten + +WAHA ist im UCC weit mehr als ein Werkzeug zum Senden einzelner WhatsApp-Nachrichten. +Im Premium-Kapitel wird der Dienst zu einem **intelligenten Kommunikationsmodul**, das auf Ereignisse in deinem System reagieren und Informationen automatisiert weitergeben kann. + +Ziel ist eine **vollständige Integration von WAHA in deine bestehende Infrastruktur** – vor allem in Verbindung mit n8n und Netdata. +So kannst du dich über wichtige Systemereignisse informieren lassen oder, optional, eingehende Nachrichten automatisch beantworten lassen – datensouverän, lokal und ohne externe Cloud-APIs. + +Das Kapitel ist in zwei praxisnahe Szenarien unterteilt: + +1. **Automatische Statusbenachrichtigung über WhatsApp** + – Wenn Netdata einen Alarm oder kritischen Wert erkennt, löst n8n automatisch eine WhatsApp-Nachricht über WAHA aus. + – Du erhältst sofort eine Benachrichtigung über Auslastung, Fehler oder Warnungen, ohne dich aktiv einloggen zu müssen. + +2. **KI-gestützte, regelkonforme Antwortfunktion** + – Eine eingehende WhatsApp-Nachricht wird von WAHA empfangen, in n8n verarbeitet und an eine lokale KI weitergeleitet. + – Die KI generiert eine personalisierte Antwort, die über WAHA zurückgesendet wird. + – Diese Variante bewegt sich aktuell **im erlaubten Rahmen**, da sie nur auf vom Nutzer initiierte Nachrichten reagiert, + liegt jedoch **im Graubereich zukünftiger Richtlinienänderungen**. + +> [!CAUTION] +> Die Nutzung einer automatisierten KI-Antwort über WAHA ist derzeit zulässig, solange jede Kommunikation vom Nutzer selbst initiiert wird +> und keine Werbung oder massenhafte Nachrichten versendet werden. +> Beachte jedoch, dass Meta die WhatsApp-Richtlinien jederzeit ändern kann. +> Sollte WhatsApp künftig KI-basierte Antworten oder WAHA-ähnliche Systeme einschränken, +> kann dieses Setup Anpassungen erfordern. + +👉 **Screenshot geeignet:** Diagramm mit Datenfluss zwischen Netdata, n8n, KI-Agent und WAHA + +Am Ende dieses Kapitels verfügst du über ein vollständig integriertes Benachrichtigungs- und Kommunikationssystem, +das deine Infrastruktur in Echtzeit überwacht und bei Bedarf automatisiert reagiert – +ein klarer Schritt in Richtung eines selbstlernenden, souveränen Kontrollzentrums. + +--- + +## Statusbenachrichtigung über WAHA + +### Schritt 1 – n8n-Workflow mit Deduplizierung und WAHA-Versand + +Ziel: Ein **n8n-Workflow** soll Systemereignisse aus Netdata empfangen, diese in Textform bringen, doppelte Alarme herausfiltern und anschließend über **WAHA** als WhatsApp-Nachricht versenden. +Damit entsteht ein zentraler Benachrichtigungsweg für kritische Zustände im gesamten UCC. + +👉 **Screenshot geeignet:** n8n-Canvas mit drei verbundenen Nodes: *Webhook (POST)* → *Function (Nachricht & Filter)* → *HTTP Request (WAHA)* + +#### Node 1 – Webhook (Trigger) +**Zweck:** Erstellt eine Empfangsadresse, über die Netdata Alarmmeldungen an n8n sendet. + +**Node-Typ:** Webhook +**Name:** Eingang – Statusalarm +**Parameter:** +- **HTTP Method:** `POST` +- **Path:** `/waha/statusalarm` +- **Response Mode:** `Last Node` +- **Response Code:** `200` + +> [!NOTE] +> Nach dem Speichern zeigt n8n automatisch die Webhook-URL an, z. B.: +> `https://n8n.deinedomain.tld/webhook/waha/statusalarm` +> Diese URL wird später in der Netdata-Alarmregel eingetragen, damit Netdata Alarme direkt an diesen Workflow sendet. + +👉 **Screenshot geeignet:** Webhook-Node mit sichtbarer URL `.../webhook/waha/statusalarm` + +#### Node 2 – Function (Nachricht aufbereiten + Dedupe) +**Zweck:** Formatiert die eingehenden Daten und verhindert, dass wiederholt identische Alarme mehrfach gesendet werden. +Die Funktion merkt sich den letzten Alarm jedes Containers für 10 Minuten. +Wenn innerhalb dieses Zeitraums derselbe Host und Alarm erneut eintreffen, wird die Nachricht unterdrückt. + +**Node-Typ:** Function +**Name:** Nachricht & Filter +**Code:** +```js +const p = items[0].json || {}; +const host = p.host || 'unbekannt'; +const alarm = p.alarm || 'Alarm'; +const status = p.status || 'warn'; +const value = (p.value !== undefined && p.value !== null) ? String(p.value) : '-'; +const when = p.when || new Date().toISOString(); + +const key = `${host}_${alarm}_${status}`; +const now = Date.now(); +const last = $flow.get(key) || 0; +const interval = 10 * 60 * 1000; // 10 Minuten + +if (now - last < interval) { + // gleicher Alarm innerhalb von 10 Minuten -> überspringen + return []; +} + +$flow.set(key, now); + +const text = + `⚠️ ${alarm}\n` + + `Host: ${host}\n` + + `Status: ${status}\n` + + `Wert: ${value}\n` + + `Zeit: ${when}`; + +return [{ json: { text } }]; +``` + +> [!TIP] +> Die Filterzeit lässt sich über die Variable `interval` anpassen. +> Für produktive Umgebungen mit vielen Containern sind 10 bis 15 Minuten meist ideal. + +👉 **Screenshot geeignet:** Function-Node mit geöffnetem Code-Editor, markiertem Kommentar `// gleicher Alarm innerhalb von 10 Minuten` + +#### Node 3 – HTTP Request (WAHA – Statusmeldung senden) +**Zweck:** Sendet die aufbereitete Nachricht über WAHA an WhatsApp. + +**Node-Typ:** HTTP Request +**Name:** WAHA – Statusmeldung senden +**Parameter:** +- **Method:** `POST` +- **URL:** + ``` + https://waha.deinedomain.tld/api/sendText + ``` +- **Headers:** + - `Content-Type`: `application/json` + - *(optional)* `Authorization`: `Bearer ` +- **Body → JSON:** + ```json + { + "chatId": "49XXXXXXXXXXX@c.us", + "text": "={{$json[\"text\"]}}" + } + ``` + +> [!NOTE] +> **Chat-ID ermitteln:** +> 1. Sende mit deinem WhatsApp-Gerät eine Testnachricht an den Ziel-Chat. +> 2. Öffne `https://waha.deinedomain.tld/api/messages`. +> 3. Kopiere den Wert `chatId` aus der letzten eingegangenen Nachricht. +> – Einzelchat endet auf `@c.us` +> – Gruppenchat endet auf `@g.us` +> 4. Trage diese ID im Node ein. + +> [!IMPORTANT] +> WAHA muss im Webinterface den Status **Connected** anzeigen. +> Bei *Pairing* oder *Disconnected* kann keine Nachricht gesendet werden. + +👉 **Screenshot geeignet:** HTTP-Request-Node mit sichtbarer `chatId` + +#### Test des Workflows +Der Workflow kann manuell getestet werden, bevor Netdata angebunden ist: + +```bash +curl -X POST "https://n8n.deinedomain.tld/webhook/waha/statusalarm" \ + -H "Content-Type: application/json" \ + -d '{ + "host": "ucc-core-01", + "alarm": "CPU high", + "status": "crit", + "value": "96%", + "when": "2025-10-20T18:42:00Z" + }' +``` + +Wenn alles funktioniert, erscheint die Meldung wenige Sekunden später als WhatsApp-Nachricht. + +👉 **Screenshot geeignet:** WhatsApp-Chat mit empfangener Meldung „⚠️ CPU high …“ + +> [!TIP] +> Wenn keine Nachricht ankommt, prüfe in n8n die **Execution Logs**. +> Dort sollte der HTTP-Request-Node den Statuscode `200` zurückgeben. +> Wird keine Ausführung gestartet, ist meist der Webhook-Pfad falsch oder Netdata erreicht den Server nicht. + +### Schritt 2 – Netdata-Alarmregel im Parent-LXC für WAHA-Benachrichtigung + +Die zentrale Netdata-Instanz im UCC empfängt bereits alle Metriken der Child-Container per Streaming. +Damit entfällt die Notwendigkeit, in jedem einzelnen LXC eigene Alarme zu konfigurieren. +Stattdessen wird **eine einzige Alarmregel** direkt im **Parent-Container** hinterlegt, +die auf aggregierte Systemwerte zugreift und bei Erreichen bestimmter Schwellwerte eine Nachricht über **n8n → WAHA** sendet. + +👉 **Screenshot geeignet:** Netdata-Parent-Dashboard mit aktivem Alarm für einen Child-Container + +> [!INFO] +> Die zentrale Überwachung mit Netdata setzt voraus, dass alle Child-LXC-Container korrekt angebunden sind. +> Im **Kapitel 15 – Netdata** wird beschrieben, wie du das Streaming-System einrichtest +> und wie die einzelnen Container ihre Metriken an den Parent weitergeben. +> Es wird **dringend empfohlen**, dieses Kapitel vollständig umzusetzen, +> bevor du hier mit der WAHA-Benachrichtigung fortfährst – +> sonst können Alarme fehlen oder falsche Hostnamen übermittelt werden. + +#### Zentrale Alarmregel anlegen + +1. Öffne auf deinem **Netdata-Parent-LXC** die Health-Konfiguration: + ```bash + nano /etc/netdata/health.d/waha_notify.conf + ``` + +2. Füge folgende Definition ein: + ``` + alarm: ucc_cpu_high + on: system.cpu + lookup: average -1m unaligned of user + system + units: % + every: 1m + warn: $this > 80 + crit: $this > 95 + exec: /usr/libexec/netdata/plugins.d/alarm-notify.sh + to: webhook + WEBHOOK_URL="https://n8n.deinedomain.tld/webhook/waha/statusalarm" + WEBHOOK_HEADER="Content-Type: application/json" + WEBHOOK_BODY="{\"host\":\"${hostname}\",\"alarm\":\"CPU high\",\"status\":\"${status}\",\"value\":\"${value}\",\"when\":\"$(date -Iseconds)\"}" + ``` + + Diese Regel löst aus, sobald die durchschnittliche CPU-Last eines überwachten Systems über **80 %** steigt (Warnung) + oder **95 %** erreicht (Kritisch). + Netdata ruft dann automatisch den im ersten Schritt erstellten **n8n-Webhook** auf, + der die Nachricht an WAHA weiterleitet. + +3. Datei speichern (STRG + O, Enter) und schließen (STRG + X). + +4. Konfiguration neu laden: + ```bash + systemctl restart netdata + ``` + +👉 **Screenshot geeignet:** geöffnete `waha_notify.conf` mit markierten Zeilen `WEBHOOK_URL` und `WEBHOOK_BODY` + +#### Test des zentralen Alarms + +Um die Funktion zu prüfen, kann ein Test-Alarm ausgelöst werden: + +```bash +sudo -u netdata /usr/libexec/netdata/plugins.d/alarm-notify.sh test webhook +``` + +Wenn die Konfiguration korrekt ist, +sollte im n8n-Log eine eingehende Anfrage erscheinen +und kurz darauf eine WhatsApp-Nachricht mit dem simulierten Alarmtext eintreffen. + +👉 **Screenshot geeignet:** WhatsApp-Chat mit empfangener Testnachricht „⚠️ CPU high … (Test)“ + +> [!NOTE] +> Diese Konfiguration gilt global für alle über Streaming verbundenen Systeme. +> Netdata sendet bei jeder betroffenen Instanz den Hostnamen automatisch mit (`${hostname}`), +> sodass du in WhatsApp genau siehst, **welcher Container** den Alarm ausgelöst hat. + +#### Erweiterung auf weitere Ressourcen + +Analog zur CPU-Überwachung können weitere Alarme hinzugefügt werden. +Dazu kopierst du den Block und passt lediglich den Metrikpfad (`on:`) und Namen (`alarm:`) an. + +Beispiele: + +**RAM-Überwachung** +``` +alarm: ucc_ram_high +on: system.ram +lookup: average -1m unaligned of used +units: % +warn: $this > 80 +crit: $this > 95 +exec: /usr/libexec/netdata/plugins.d/alarm-notify.sh +to: webhook +WEBHOOK_URL="https://n8n.deinedomain.tld/webhook/waha/statusalarm" +WEBHOOK_HEADER="Content-Type: application/json" +WEBHOOK_BODY="{\"host\":\"${hostname}\",\"alarm\":\"RAM high\",\"status\":\"${status}\",\"value\":\"${value}\",\"when\":\"$(date -Iseconds)\"}" +``` + +**Speicherplatz-Überwachung** +``` +alarm: ucc_disk_low +on: disk_space._ +lookup: max -5m unaligned of used +units: % +warn: $this > 85 +crit: $this > 95 +exec: /usr/libexec/netdata/plugins.d/alarm-notify.sh +to: webhook +WEBHOOK_URL="https://n8n.deinedomain.tld/webhook/waha/statusalarm" +WEBHOOK_HEADER="Content-Type: application/json" +WEBHOOK_BODY="{\"host\":\"${hostname}\",\"alarm\":\"Disk usage high\",\"status\":\"${status}\",\"value\":\"${value}\",\"when\":\"$(date -Iseconds)\"}" +``` + +> [!TIP] +> So entsteht eine skalierbare Struktur mit mehreren einfachen Health-Regeln, +> die alle denselben Webhook nutzen. +> Dadurch bleibt das System wartungsarm, aber du erhältst bei kritischen Zuständen sofort eine Nachricht auf dein Smartphone. + +--- + +## Premium – Elyra: Intelligente WhatsApp-Interaktion mit Opt-In-Trigger + +In diesem Premium-Abschnitt erweiterst du dein bestehendes WAHA-Setup um **Elyra** – +eine KI-Instanz, die über WhatsApp gezielt auf Nachrichten reagiert, wenn sie vom Nutzer aktiviert wird. +Dadurch bleibt die Nutzung im Rahmen der WhatsApp-Richtlinien, da Elyra niemals selbstständig Kontakt aufnimmt. + +👉 **Screenshot geeignet:** WhatsApp-Chat mit „Ich brauche deine Hilfe, Elyra“ als Startbefehl und automatischer Antwort + +> [!NOTE] +> Elyra ist ein optionales Modul, das lokale oder externe KI-Modelle (z. B. OpenAI, Ollama) ansprechen kann. +> Die Integration setzt ein funktionierendes WAHA- und n8n-System aus dem Free-Kapitel voraus. +> +> Der Ansatz bewegt sich in einem **zulässigen Graubereich**, +> da die Kommunikation ausschließlich **user-initiiert** erfolgt und somit kein unerlaubtes Messaging stattfindet. + +### Aktivierungslogik + +Elyra reagiert nur, wenn sie bewusst aktiviert wird. +Die Aktivierung erfolgt über eine eindeutige Eingabe, die als **Opt-In-Trigger** dient: + +**Trigger-Phrase:** +> „Ich brauche deine Hilfe, Elyra“ + +Sobald diese Nachricht eingeht, aktiviert n8n den zugehörigen Workflow +und leitet den Inhalt an den KI-Knoten weiter. +Elyra verarbeitet die Anfrage, erstellt eine Antwort und sendet sie über WAHA an den Chat zurück. + +### Beendigungslogik + +Die Sitzung endet automatisch, wenn: + +1. Der Nutzer „Danke, Elyra“ schreibt, **oder** +2. **10 Minuten** lang keine neue Nachricht eingeht. + +Beide Bedingungen setzen den Workflow-Status zurück, +sodass Elyra keine weiteren Nachrichten beantwortet, bis erneut ein gültiger Trigger empfangen wird. + +> [!TIP] +> Dieses Verhalten entspricht dem Prinzip klassischer Sprachassistenten wie „Hey Siri“ oder „Alexa“ +> und sorgt für klare Grenzen zwischen aktiver und passiver Phase. + +### Beispielhafte Gesprächssequenz + +``` +👤 Nutzer: Ich brauche deine Hilfe, Elyra +🤖 Elyra: Natürlich. Wobei darf ich dir helfen? +👤 Nutzer: Wann ist der nächste Stream? +🤖 Elyra: Der nächste Stream findet am Freitag um 19:30 Uhr statt – Thema: Disney Dreams 🌟 +👤 Nutzer: Danke, Elyra +🤖 Elyra: Gern geschehen. Ich bin wieder im Ruhemodus. +``` + +👉 **Screenshot geeignet:** WhatsApp-Chat mit Elyra, die freundlich auf eine Zuschauerfrage reagiert und danach automatisch inaktiv wird. + +### Technische Grundlage + +Die Logik besteht aus einer kleinen n8n-Kette mit klar definierten Knoten: + +| Node | Aufgabe | +|------|----------| +| **Webhook (Trigger)** | empfängt eingehende WhatsApp-Nachrichten über WAHA | +| **IF (Bedingung)** | prüft, ob die Nachricht „Ich brauche deine Hilfe, Elyra“ enthält | +| **KI-Node (OpenAI / Ollama)** | verarbeitet den Text und erstellt eine Antwort | +| **HTTP Request → WAHA** | sendet die Antwort an den Chat | +| **Wait / Timeout-Node** | beendet nach 10 Minuten Inaktivität | +| **IF („Danke, Elyra“) → Stop** | erkennt das manuelle Opt-Out und stoppt sofort | + +Elyra interagiert damit ausschließlich auf Anfrage, +arbeitet ressourcenschonend und wahrt alle datenschutzrelevanten Grenzen. + +> [!IMPORTANT] +> Elyra darf **niemals eigenständig** Nachrichten senden oder neue Chats starten. +> Jede Kommunikation muss eindeutig vom Nutzer ausgehen. +> Nur so bleibt die Nutzung im Einklang mit den WhatsApp-AGB. + +Mit dieser Implementierung erhält dein UCC eine intelligente, aber kontrollierte Interaktionsebene, +die sinnvoll zwischen Automatisierung und Nutzerhoheit vermittelt. +