WhatsApp

WhatsApp ist eine der beliebtesten Messaging-Plattformen weltweit. Mit Selus verwalteter WhatsApp-Bridge kannst du direkt aus WhatsApp mit deinen Agenten chatten — keine zusätzlichen Apps nötig.

Hinweis

Die WhatsApp-Integration benötigt eine Telefonnummer und nutzt WhatsApp Webs Multi-Device-Funktion. Derzeit wird nur eine WhatsApp-Pipe pro Selu-Instanz unterstützt.

So funktioniert es

Selu betreibt einen verwalteten Bridge-Container, der sich über die Baileys-Bibliothek mit WhatsApp verbindet (dieselbe Technologie hinter WhatsApp Web). Die Bridge:

• Koppelt sich per QR-Code mit deinem WhatsApp-Konto
• Empfängt Nachrichten aus ausgewählten Chats
• Leitet Agenten-Antworten zurück an WhatsApp
• Hält die Verbindung automatisch aufrecht

Die gesamte WhatsApp-Bridge-Verwaltung wird von Selu übernommen — keine manuellen Docker-Befehle oder Konfigurationsdateien nötig.

Schritt 1: WhatsApp-Pipe einrichten

1. Öffne Selu und gehe zu Pipes.
2. Klicke auf Pipe hinzufügen und wähle WhatsApp.
3. Gib deiner Pipe einen beschreibenden Namen wie “Persönliches WhatsApp” oder “Team WhatsApp”.
4. Optional: Füge einen Authorization-Header hinzu, falls dein Setup das erfordert (die meisten Nutzer können das leer lassen).
5. Klicke auf WhatsApp einrichten.

Selu lädt den WhatsApp-Bridge-Container automatisch herunter und startet ihn im Hintergrund. Das kann beim ersten Mal ein bis zwei Minuten dauern.

Schritt 2: Handy koppeln

1. Nach Abschluss der Einrichtung siehst du einen QR-Code auf der WhatsApp-Detailseite.
2. Öffne WhatsApp auf deinem Handy.
3. Gehe zu Einstellungen → Verknüpfte Geräte (oder Einstellungen → WhatsApp Web bei älteren Versionen).
4. Tippe auf Gerät verknüpfen und scanne den QR-Code.
5. Warte, bis der Verbindungsstatus “Verbunden” zeigt.

Achtung

Der QR-Code läuft nach wenigen Minuten ab. Falls er nicht funktioniert, lade die Seite neu, um einen neuen zu erzeugen.

Schritt 3: Erlaubte Chats wählen

Standardmäßig antwortet deine WhatsApp-Pipe auf keine Nachrichten — du musst aus Sicherheitsgründen explizit bestimmte Chats erlauben.

1. Scrolle auf der WhatsApp-Detailseite zu “Wer kann diese Pipe nutzen?”.
2. Nutze die Chat-Suche, um Unterhaltungen aus deinem WhatsApp-Konto zu finden.
3. Wähle einen Chat und bestimme, welchem Selu-Nutzer er zugeordnet werden soll.
4. Klicke auf Person hinzufügen.

Chat-Erkennung

Nur Chats mit kürzlicher Aktivität erscheinen in den Suchergebnissen. Falls ein Chat fehlt, sende eine Nachricht in dieser WhatsApp-Unterhaltung und suche dann erneut.

Schritt 4: Loschatten

Sende eine Nachricht in einem deiner erlaubten WhatsApp-Chats. Dein Selu-Agent empfängt die Nachricht und antwortet direkt in WhatsApp — wie eine Unterhaltung mit einem Freund.

Selbstnachrichten

Du kannst dir selbst auf WhatsApp schreiben, um einen privaten Chat mit deinen Agenten zu erstellen. Das ist besonders nützlich für persönliche Assistenten oder schnelle Fragen.

Experimentelles Feature

Selbstnachrichten auf WhatsApp sind experimentell und können unzuverlässig sein, besonders auf dem iPhone. Für die stabilste Erfahrung nutze einen dedizierten Chat mit einem anderen Kontakt oder erstelle eine WhatsApp-Gruppe.

Tool-Genehmigungen in WhatsApp

Genau wie bei Telegram und iMessage unterstützt WhatsApp Tool-Genehmigungen, wenn deine Agenten Erlaubnis zum Handeln brauchen:

1. Agent benötigt ein Tool mit Nachfragen-Policy
2. Du erhältst eine WhatsApp-Nachricht, die die Aktion beschreibt
3. Antworte mit “ja”, “genehmigen”, “ok” oder ähnlich zum Erlauben
4. Antworte mit “nein”, “verweigern”, “abbrechen” zum Blockieren

Da WhatsApp kein eingebautes Antwort-Threading hat, ordnet Selu deine Antwort automatisch zu, wenn nur eine Genehmigung aussteht. Falls mehrere Tools gleichzeitig Genehmigung brauchen, antworte der Reihe nach auf jede.

Sicherheit und Datenschutz

Chat-Erlaubnislisten

Nur explizit erlaubte Chats können deine Agenten erreichen. Selbst wenn jemand deine Telefonnummer hat, kann er nicht mit Selu interagieren, es sei denn, du hast seinen Chat zur Erlaubnisliste hinzugefügt.

Lokale Verarbeitung

Die WhatsApp-Bridge läuft auf deinem Selu-Server — keine Nachrichten werden an Drittanbieter-Dienste gesendet, außer an den konfigurierten LLM-Anbieter des Agenten.

Verbindungssicherheit

Die Bridge nutzt WhatsApps offizielles Multi-Device-Protokoll mit Ende-zu-Ende-Verschlüsselung. Deine Login-Session wird lokal in einem verschlüsselten Docker-Volume gespeichert.

WhatsApp-Pipe verwalten

Verbindungsstatus anzeigen

Die WhatsApp-Detailseite zeigt:

• Bridge-Status — Ob der Bridge-Container läuft
• Telefonverbindung — Verbindungsstatus mit WhatsApp-Servern
• WhatsApp-Konto — Welche Telefonnummer verbunden ist
• Erlaubte Chats — Wer deinen Agenten Nachrichten senden kann

Verbindungsprobleme beheben

Falls WhatsApp-Nachrichten Selu nicht erreichen:

1. Bridge-Status prüfen — Stelle sicher, dass auf der Detailseite “Ready” angezeigt wird.
2. Telefonverbindung überprüfen — Der Verbindungsstatus sollte “Connected” oder “Open” sein.
3. Chat-Erlaubnisliste bestätigen — Der Absender muss in deiner Erlaubnisliste sein.
4. Mit einfacher Nachricht testen — Versuche zuerst “hallo”, bevor du komplexe Anfragen sendest.

Verbindung erneuern

Falls die Verbindung instabil wird:

1. Gehe zur WhatsApp-Detailseite.
2. Beachte den aktuellen Verbindungsstatus.
3. Falls “Getrennt” oder Fehler angezeigt werden, versuche die Seite neu zu laden.
4. Falls Probleme bestehen bleiben, musst du möglicherweise einen neuen QR-Code scannen.

WhatsApp-Integration entfernen

Um WhatsApp zu trennen:

1. Gehe zu Pipes und finde deine WhatsApp-Pipe.
2. Öffne die Detailseite.
3. Scrolle nach unten und klicke auf WhatsApp-Pipe entfernen.
4. Bestätige die Entfernung.

Das wird:

• Den Bridge-Container stoppen
• Deine WhatsApp-Login-Session löschen
• Alle erlaubten Chat-Zuordnungen entfernen
• Nachrichten-Routing von WhatsApp deaktivieren

Vollständige Entfernung

Das Entfernen der Pipe löscht auch deine WhatsApp-Login-Session. Du musst dein Handy erneut koppeln, wenn du WhatsApp in Zukunft wieder einrichtest.

Einschränkungen

• Eine Pipe pro Instanz — Selu unterstützt derzeit eine aktive WhatsApp-Pipe gleichzeitig
• Handy-Abhängigkeit — Dein Handy braucht Internetzugang, um die WhatsApp-Web-Session aufrechtzuerhalten
• Rate Limits — WhatsApp kann Konten drosseln oder sperren, die zu viele automatisierte Nachrichten senden
• Gruppenchat-Komplexität — Agenten-Antworten in Gruppenchats werden möglicherweise nicht immer korrekt mit der ursprünglichen Nachricht verknüpft

Erweiterte Konfiguration

Authorization-Header

Falls du Selu hinter zusätzlichen Sicherheitsschichten betreibst, kannst du die Bridge so konfigurieren, dass sie benutzerdefinierte Authorization-Header enthält, wenn sie sich mit Selu verbindet:

1. Fülle während der Einrichtung das Feld “Authorization Header” aus
2. Gib den vollständigen Header-Wert an (z. B. Bearer dein-geheimer-token)
3. Dieser Header wird mit allen Nachrichten von der Bridge an Selu gesendet

Netzwerk-Konfiguration

Die WhatsApp-Bridge erkennt deine Docker-Netzwerk-Konfiguration automatisch. Falls du ein benutzerdefiniertes Docker-Setup verwendest:

• Bridge-Port — Die Bridge hört auf Port 3200 in ihrem Container
• Netzwerk-Erkennung — Selu erkennt dein Docker-Compose-Netzwerk automatisch
• Fallback-Modus — Falls die Netzwerk-Erkennung fehlschlägt, nutzt die Bridge Host-Networking mit Port-Mapping

Datenpersistenz

WhatsApp-Login-Sessions werden in einem Docker-Volume namens selu-whatsapp-bridge-data gespeichert. Dieses Volume enthält:

• WhatsApp-Authentifizierungsdaten
• Session-Status und Verschlüsselungsschlüssel
• Chat-Metadaten und Nachrichtenverlauf

Backup-Hinweis

Wenn du deine Selu-Installation sicherst, schließe das WhatsApp-Bridge-Daten-Volume ein, um ein erneutes Koppeln deines Handys nach der Wiederherstellung zu vermeiden.

Fehlerbehebung

Bridge startet nicht

Falls die WhatsApp-Bridge nicht startet:

1. Docker prüfen — Stelle sicher, dass Docker läuft und für Selu zugänglich ist
2. Berechtigungen überprüfen — Der Selu-Container braucht Zugriff auf den Docker-Socket
3. Systemressourcen prüfen — Die Bridge benötigt mindestens 512MB RAM
4. Logs überprüfen — Prüfe die Selu-Logs auf Bridge-Startfehler

QR-Code erscheint nicht

Falls du keinen QR-Code auf der Detailseite siehst:

1. Kurz warten — Die Bridge startet möglicherweise noch
2. Seite neu laden — QR-Codes werden dynamisch generiert
3. Bridge-Status prüfen — Stelle sicher, dass die Bridge als “Running” angezeigt wird
4. Bei Bedarf neu starten — Entferne die Pipe und erstelle sie neu, falls die Bridge hängt

Nachrichten erreichen Agenten nicht

Falls WhatsApp-Nachrichten nicht verarbeitet werden:

1. Erlaubte Chats prüfen — Überprüfe, ob der Absender in deiner Erlaubnisliste ist
2. Pipe-Status bestätigen — Die Pipe muss aktiv und verbunden sein
3. Agenten-Antwort testen — Versuche zuerst eine Nachricht über den Web-Chat
4. Nachrichtenformat prüfen — Sehr lange Nachrichten oder Mediendateien werden möglicherweise gefiltert

Performance-Probleme

Falls WhatsApp-Antworten langsam sind:

1. Systemlast prüfen — Mehrere Agenten oder komplexe Aufgaben können Verzögerungen verursachen
2. Netzwerk überprüfen — Schlechte Internetverbindung beeinflusst beide Richtungen
3. Bridge-Ressourcen überwachen — Die Bridge benötigt möglicherweise mehr Speicher für aktive Konten
4. Agenten-Komplexität prüfen — Einfachere Agenten antworten typischerweise schneller