Kapitel 18/Free Rohtext.md hinzugefügt

2025-10-19 19:19:21 +00:00
parent 45c9528291
commit 10ae311dac
1 changed files with 525 additions and 0 deletions
--- a/Rohtext.md
+++ b/Rohtext.md
@@ -0,0 +1,525 @@
+# Kapitel 18 – 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.
+