# Blueprint: WhatsApp-Bridge

Version 1.0 · denzer.ai · Lizenz: frei nutzbar mit Quellenangabe

Eine eigene WhatsApp-Bridge, mit der dein Agent eingehende Nachrichten liest, Kontakte findet und auf deinen Befehl Nachrichten verschickt. Komplett lokal auf deinem Rechner oder Server, keine Drittanbieter-Cloud zwischen dir und WhatsApp.

**Fallbeispiel.** Du bekommst täglich 30 bis 80 WhatsApp-Nachrichten, viele davon sind kurze Kunden-Anfragen und Termin-Bestätigungen. Dein Agent soll die Inbox sehen, Drafts in deinem Schreibstil vorschlagen und auf dein "Okay schick raus" senden. Niemals von selbst senden. Auch Gruppen-Übersicht und Suche über alle Chats hinweg sollen drin sein.

---

## Teil B — Für dich (Operator)

### Was ist das?

WhatsApp hat keine offene Schnittstelle für normale Nutzer, nur die teure Business-API. Stattdessen baust du dir eine kleine Brücke, die genauso funktioniert wie WhatsApp Web im Browser: einmaliger QR-Code-Login mit deinem Handy, danach hält ein kleiner Hintergrund-Prozess die Verbindung. Dein Agent fragt diesen Prozess an, wenn er Nachrichten lesen oder senden soll.

Diese Brücke ist deine private Instanz. Niemand sonst sieht deine Nachrichten, alles bleibt auf deinem Rechner.

### Warum so und nicht anders?

WhatsApp bietet drei Wege, an seine Nachrichten zu kommen: die offizielle **Business-API** (teuer, aufwändige Verifikation, Template-Pflicht), Drittanbieter-SaaS-Bridges wie Twilio (laufende Kosten, deine Nachrichten gehen durch fremde Server), oder eine eigene **WhatsApp-Web-Brücke** auf Basis von baileys oder whatsapp-web.js (kostenlos, lokal, aber inoffiziell).

Dieser Blueprint nimmt den dritten Weg. Vorteil: keine laufenden Kosten, keine Drittpartei zwischen dir und WhatsApp, Outbound bleibt unter deiner Kontrolle. Nachteil: ist eine inoffizielle Schnittstelle, kann bei größeren Updates kurz brechen. Für **persönliche und kleinunternehmerische** Nutzung das beste Verhältnis. Für Massenversand oder echte SaaS-Produkte wäre die Business-API der saubere Weg.

SQLite statt Cloud-DB, weil deine Chats privat sind und du keine Inhalts-Replikation auf fremde Server willst. FastAPI als REST-Wrapper, weil dein Agent sowieso lokal mit HTTP arbeitet.

### Was brauchst du dafür?

- Ein WhatsApp-Konto auf deinem Handy (normales WhatsApp reicht, kein Business)
- Einen Rechner, der mehr oder weniger durchlaufen kann (eigener Mac, Mini-Server, oder Cloud-VPS für ein paar Euro pro Monat)
- Etwas Speicher: nach einem Jahr WhatsApp-Sync rund 1–3 GB

### Wie startest du?

1. Du lädst dir unten den Starter herunter und gibst ihn deinem Agent
2. Du sagst zum Beispiel "richte mir die WhatsApp-Bridge ein"
3. Dein Agent installiert die nötigen Pakete und startet das Login-Script
4. Du scannst den angezeigten QR-Code einmal mit deinem Handy (genau wie bei WhatsApp Web)
5. Ab dann läuft die Verbindung, deine Nachrichten landen in einer lokalen Datenbank, dein Agent kann lesen, suchen und Drafts vorbereiten

### Wo sind die Grenzen?

- Massenversand wird von WhatsApp erkannt und führt zu Sperrung — nutze die Brücke für deine **persönliche** Kommunikation, nicht für Newsletter
- Wenn dein Handy sieben Tage offline ist, trennt WhatsApp die Web-Sitzung — du musst neu scannen
- Sprachnachrichten kommen als Audio-Datei rein, Transkription läuft optional über Whisper
- Auto-Send niemals erlauben. Auch nicht "fast immer". **Sende-Befehl ist Sende-Befehl, alles andere ist Draft.**

### Was kostet das?

- Software: kostenlos (Open Source)
- Wenn du selbst hostest: 0–5 € pro Monat für einen kleinen VPS
- Modell-Kosten für Drafts: ein paar Cent pro Tag

### Wann lohnt es sich, wann nicht?

Lohnt sich, wenn dir WhatsApp Kommunikationskanal Nummer eins ist und du den Inbox-Druck reduzieren willst. Lohnt sich nicht, wenn du WhatsApp nur sporadisch nutzt — dann ist der Aufwand nicht gerechtfertigt.

### Wie weißt du, dass es funktioniert?

Du siehst die Anzahl deiner WhatsApp-Chats in der Agent-Oberfläche, kannst nach einem Kontakt suchen, eine Antwort als Draft generieren lassen und mit einem Klick rausschicken. Wenn die Verbindung bricht, gibt es einen klaren Status "offline, neuer Scan nötig".

### Stolpersteine

- **Telefonnummer-Format.** WhatsApp arbeitet mit `@c.us`-Suffix für Einzelchats und `@g.us` für Gruppen. Wenn du Nummern manuell eingibst, vergiss die Landesvorwahl nicht
- **Multi-Device.** Wenn du WhatsApp parallel auf mehreren Geräten nutzt, kann der Sync zwischen Brücke und Handy ein paar Sekunden brauchen
- **Sperrung wegen Spam-Erkennung.** Sende-Geschwindigkeit drosseln, niemals identische Nachrichten an viele Empfänger
- **DSGVO.** Wenn du Kundennachrichten lokal speicherst, brauchst du eine Verfahrensbeschreibung. Bei rein persönlichen Chats keine Pflicht

---

## Teil A — Für deinen Agent

### Agent-Triggersätze

- "Richte mir die WhatsApp-Bridge ein"
- "Bau mir eine lokale WhatsApp-Anbindung"
- "Verbinde Klaus mit meinem WhatsApp"

### Ziel

Lokale WhatsApp-Bridge mit eigenem Sync-Prozess (baileys oder whatsapp-web.js), Persistenz in SQLite, REST-API für Lesen/Suchen/Senden. Outbound nur auf expliziten User-Befehl, niemals autonom.

### Erfolgskriterien

- Eingehende Nachrichten landen innerhalb 1–2 Sekunden in lokaler DB
- Outbound nur über `POST /api/whatsapp/send` mit explizitem User-Trigger
- Session überlebt Reboot, Re-Login nur bei abgelaufenem QR oder Handy 7+ Tage offline
- Find-Contact, Recent-Chats, Search, Media-Download als eigene Endpoints
- Keine Drittanbieter-Cloud, alles lokal

### Eingabe-Schema

```yaml
bridge:
  engine:          "baileys" | "whatsapp-web.js"     # baileys leichter, web.js stabiler
  data_dir:        "<root>/data/whatsapp"
  db_path:         "<root>/data/whatsapp/whatsapp.db"
  qr_strategy:     "terminal" | "html"               # html liefert /qr.html, scanbar im Browser
api:
  bind:            "127.0.0.1:8890"                  # lokal, niemals 0.0.0.0
  auth:            "none"                            # lokal, keine Auth nötig
sync:
  history_days:    30                                # Anzahl Tage historischer Chats beim ersten Login
  media_dir:       "<root>/data/whatsapp/media"
outbound:
  rate_limit:      "max 5/min, max 30/h"
  preview_pflicht: true                              # NIE ohne User-Trigger senden
```

### Verarbeitung

1. **Login** — QR-Code generieren, User scannt mit Handy, Session-Files in `data_dir/auth/`
2. **Sync** — eingehende Nachrichten via Event-Listener in DB schreiben (Tabellen `chats`, `messages`, `media`)
3. **API** — REST-Endpoints für Lesen, Suchen, Kontakt-Suche, Senden
4. **Send** — Eingangs-Validierung (chat_id-Format, Text nicht leer), an Engine weiterreichen
5. **Watchdog** — Verbindungs-Status periodisch prüfen, bei Bruch Reconnect (max 3 Versuche)

### Endpoints

| Methode | Pfad | Zweck |
|---|---|---|
| GET | `/api/whatsapp/chats?limit=200` | Letzte Chats inkl. Unread |
| GET | `/api/whatsapp/messages?chat_id=...&limit=100` | Nachrichten eines Chats |
| GET | `/api/whatsapp/find-contact?name=Jasper` | Kontakt per Name suchen |
| GET | `/api/whatsapp/search?q=...` | Volltextsuche über alle Chats |
| GET | `/api/whatsapp/media?msg_id=...` | Media-Datei abrufen |
| POST | `/api/whatsapp/send` | Nachricht senden, Body: `{chat_id, text}` |

### Sicherheit

- API bindet **ausschließlich** an `127.0.0.1`, niemals an externe Interfaces ohne weitere Auth-Schicht
- Auth-Files in `data_dir/auth/` mit chmod 600
- Outbound-Endpoint loggt jeden Send mit User-Trigger-ID (welche Agent-Session, welche User-Bestätigung)
- Send-Rate gedrosselt, sonst WhatsApp-Sperrung

### Fehler-/Edge-Cases

- QR abgelaufen → neuen QR generieren, Operator-Hinweis
- Handy 7+ Tage offline → Session ungültig, voller Neu-Login nötig
- Verbindung bricht → 3× Reconnect mit exponential Backoff, dann Alarm
- chat_id-Format ungültig → 400, kein Sende-Versuch
- Engine wirft Error beim Senden → bis zu 2× retry, dann Status `failed`, Operator-Hinweis

### Verzeichnisstruktur

```
<root>/
├── whatsapp-bridge/
│   ├── login.js              # QR-Login + Initial-Sync
│   ├── sync.js               # Event-Loop, in DB schreiben
│   ├── send.js               # Send-Endpoint
│   ├── schema.sql            # Tabellen chats, messages, media
│   ├── package.json
│   └── auth/                 # Session-Files, gitignored
└── data/whatsapp/
    ├── whatsapp.db
    └── media/
```

### Code-Snippets

Im Starter findest du `login.js` (QR-Login mit baileys), `sync.js` (Event-Listener), `send.js` (Outbound), `schema.sql` (DB-Schema) und ein FastAPI-Beispiel für den REST-Wrapper. Dein Agent integriert die Files in dein Projekt und passt Pfade an.

---

## Teil C — Was du als Nächstes tust

1. Starter unten laden
2. Markdown + ZIP deinem Agent geben
3. Sagen: "richte mir die WhatsApp-Bridge ein"
4. QR-Code mit dem Handy scannen
5. Ersten Test schicken: `find-contact` mit deinem eigenen Namen, dann `send` an dich selbst mit Text "Test"
6. Eingehende Nachrichten in der Agent-Oberfläche prüfen
7. Erst dann produktiv nutzen

### Lern-Checkliste

- Wo liegt meine Session und was passiert, wenn ich sie lösche?
- Welche Endpoints darf mein Agent ohne Rückfrage aufrufen, welche nur mit meiner Bestätigung?
- Wie erkenne ich, dass die Verbindung weg ist?
- Wie melde ich mich neu an, wenn die Sitzung verfällt?
- Welche Daten landen wo, und wie würde ich sie wieder löschen?

Fragen: christian@denzer.ai