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.