diff --git a/Kapitel 18/Free Rohtext.md b/Kapitel 18/Free Rohtext.md new file mode 100644 index 0000000..6884b92 --- /dev/null +++ b/Kapitel 18/Free 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@ + ``` + Ersetze `` 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@ +``` + +> [!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://: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** | `` | +| **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. +