Thomas/Homelab--Bratonein-Kontrollzentrum--Tutorial

Files

Thomas Dannenberg 10ae311dac Kapitel 18/Free Rohtext.md hinzugefügt

2025-10-19 19:19:21 +00:00

18 KiB

Raw Blame History

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:
```
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:

apt update && apt upgrade -y

Nach Abschluss den Container neu starten:

reboot

Anschließend erneut per SSH anmelden:

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.

apt install -y ca-certificates curl gnupg lsb-release

Nun wird das offizielle Docker-Repository hinzugefügt und die aktuelle Engine installiert:

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:

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:

mkdir -p /opt/waha
cd /opt/waha

Lege anschließend die Unterordner für Konfiguration, Logs und Daten an:

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:

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.

nano /opt/waha/docker-compose.yml

Füge folgenden Inhalt ein:

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:

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:

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:

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:
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

Öffne das Dashboard des Nginx Proxy Manager.
Klicke auf Add Proxy Host.
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:
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:

curl https://waha.deinedomain.tld/api/sessions

Die Ausgabe sollte in etwa so aussehen:

[
  {
    "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):

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:

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:
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:

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:

reboot

Nach dem Reboot erneut einloggen und prüfen, ob der Dienst automatisch gestartet wurde:

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:
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:

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.

18 KiB Raw Blame History Unescape Escape

Kapitel 18 – WAHA (WhatsApp HTTP API)

Einleitung

Voraussetzungen & Ressourcen

Container-Ressourcen

Technische Voraussetzungen

Schritt-für-Schritt-Anleitung

Schritt 1 – Container vorbereiten und System aktualisieren

Schritt 2 – Docker installieren und vorbereiten

Schritt 3 – Verzeichnisstruktur und Konfiguration anlegen

Schritt 4 – Container starten und erste Verbindung prüfen

Schritt 5 – Integration in Nginx Proxy Manager (NPM)

Proxy-Host anlegen

Verbindung prüfen

Schritt 6 – Erste API-Tests und Nachrichten senden

Verbindung prüfen

Testnachricht senden

Nachrichten empfangen

Schritt 7 – Dauerbetrieb und Neustart-Verhalten prüfen

18 KiB

Raw Blame History