Matrix Messenger-Bridges¶
Uebersicht¶
Lokaler Matrix-Server (Continuwuity) als universeller Message-Bus fuer Messenger-Bridges. Jeder Agent kann eigene WhatsApp-/Telegram-/Signal-Nummern betreiben. Alles laeuft lokal auf dem Server — keine externen Dienste, keine Cloud-API.
WhatsApp ←→ mautrix-whatsapp ←→ Continuwuity ←→ Comm-Hub
Telegram ←→ mautrix-telegram ←→ (lokal) ←→ Genesis AI
Signal ←→ mautrix-signal ←→ ←→ Frontend
Architektur¶
| Container | Image | Port (intern) | Aufgabe |
|---|---|---|---|
| matrix-conduit | continuwuity:latest | 6167 | Matrix Homeserver (Rust, ~50 MB RAM) |
| matrix-whatsapp | mautrix/whatsapp:latest | 29318 | WhatsApp-Bridge (Multi-Account) |
| matrix-telegram | mautrix/telegram:latest | 29317 | Telegram-Bridge (Multi-Account) |
Alle Container laufen im ai-network, sind nicht von aussen erreichbar.
Datenfluss¶
Eingehende WhatsApp-Nachricht:
Handy → WhatsApp-Server → mautrix-whatsapp → Continuwuity (Matrix Room)
→ Comm-Hub (matrix-nio Client) → Routing → Agent / Genesis AI
Ausgehende Antwort:
Agent/Genesis → Comm-Hub → Continuwuity → mautrix-whatsapp → WhatsApp-Server → Handy
Cross-Messenger Bridging¶
Wenn beide Bridges aktiv sind, koennen Nachrichten zwischen Messengern gebrückt werden:
Dafuer muessen beide Bridges in denselben Matrix-Raum eingeladen werden.
Konfiguration¶
Pfade¶
| Pfad | Inhalt |
|---|---|
/etc/xynap/matrix/conduit/conduit.toml |
Continuwuity Server-Config |
/etc/xynap/matrix/conduit/whatsapp-registration.yaml |
WhatsApp Appservice-Registrierung |
/etc/xynap/matrix/conduit/telegram-registration.yaml |
Telegram Appservice-Registrierung |
/etc/xynap/matrix/whatsapp/config.yaml |
WhatsApp Bridge-Config (Referenz) |
/etc/xynap/matrix/telegram/config.yaml |
Telegram Bridge-Config (Referenz) |
/var/lib/xynap/matrix/conduit/ |
Continuwuity Datenbank (RocksDB) |
/var/lib/xynap/matrix/whatsapp/ |
WhatsApp Bridge-Daten + Config |
/var/lib/xynap/matrix/telegram/ |
Telegram Bridge-Daten + Config |
Continuwuity (Matrix Server)¶
# /etc/xynap/matrix/conduit/conduit.toml
[global]
server_name = "matrix.xynap.local" # Nur intern
allow_federation = false # Kein externer Zugriff
port = 6167
allow_registration = false # Nur via Appservice
Keine Federation — der Server kommuniziert ausschliesslich mit den lokalen Bridges.
Matrix Admin-Account¶
| Feld | Wert |
|---|---|
| User-ID | @admin:matrix.xynap.local |
| Admin-Room | Automatisch erstellt beim Start |
| Zugang | Nur intern via Matrix Client-Server API |
WhatsApp Bridge (mautrix-whatsapp)¶
Die Bridge nutzt das offizielle WhatsApp Web Multi-Device Protokoll (whatsmeow). Multi-Account: Jeder Matrix-User kann seine eigene WhatsApp-Nummer verbinden.
Wichtige Config-Felder in /var/lib/xynap/matrix/whatsapp/config.yaml:
homeserver:
address: http://matrix-conduit:6167
domain: matrix.xynap.local
appservice:
address: http://matrix-whatsapp:29318
hostname: 0.0.0.0
port: 29318
bridge:
permissions:
"*": relay
"matrix.xynap.local": user
"@admin:matrix.xynap.local": admin
Telegram Bridge (mautrix-telegram)¶
Benoetigt einen Telegram API Key von my.telegram.org/apps.
Config in /var/lib/xynap/matrix/telegram/config.yaml:
Betrieb¶
Container starten/stoppen¶
# Gesamter Matrix-Stack
sudo docker compose -f /etc/xynap/stack/docker-compose.yml up -d matrix-conduit matrix-whatsapp matrix-telegram
# Einzelne Bridge neustarten
sudo docker compose -f /etc/xynap/stack/docker-compose.yml restart matrix-whatsapp
# Logs
sudo docker logs -f matrix-whatsapp
sudo docker logs -f matrix-conduit
WhatsApp-Nummer verbinden¶
- Matrix-User erstellen (falls noch nicht vorhanden)
- Dem WhatsApp-Bot
@whatsappbot:matrix.xynap.localeine Nachricht senden:login - QR-Code scannen mit WhatsApp → Verknuepfte Geraete → Geraet hinzufuegen
- Status pruefen:
statusan den Bot senden
Jeder Matrix-User kann seinen eigenen WhatsApp-Account verbinden — die Bridge verwaltet mehrere Sessions.
Telegram-Account verbinden¶
- Dem Telegram-Bot
@telegrambot:matrix.xynap.localschreiben:login - Telefonnummer eingeben
- Bestaetigungscode aus Telegram eingeben
- Optional: 2FA-Passwort eingeben
Appservice-Verwaltung (Admin-Room)¶
!admin appservices list # Registrierte Bridges anzeigen
!admin appservices register # Neue Bridge registrieren (YAML als Code-Block)
!admin appservices unregister NAME # Bridge entfernen
Multi-Agent Setup¶
Jeder Agent erhaelt einen eigenen Matrix-User:
@agent-42:matrix.xynap.local → WhatsApp +49 170 1234567
@agent-7:matrix.xynap.local → WhatsApp +49 171 9876543
@agent-42:matrix.xynap.local → Telegram @agent42_bot
Der Comm-Hub ueberwacht die Matrix-Raeume und routet Nachrichten automatisch an den richtigen Agent.
Troubleshooting¶
"as_token was not accepted"¶
Die Tokens in der Bridge-Config muessen mit der Appservice-Registrierung uebereinstimmen:
# Token in Registrierung
grep as_token /etc/xynap/matrix/conduit/whatsapp-registration.yaml
# Token in Bridge-Config
grep as_token /var/lib/xynap/matrix/whatsapp/config.yaml
Beide muessen identisch sein. Nach Aenderung: Bridge neustarten.
"telegram.api_hash not configured"¶
Telegram API-Credentials fehlen. Erstelle eine App auf my.telegram.org/apps und trage api_id + api_hash ein.
Bridge reconnected nicht¶
# Session-Daten loeschen und neu pairen
sudo rm -rf /var/lib/xynap/matrix/whatsapp/whatsmeow-*
sudo docker compose -f /etc/xynap/stack/docker-compose.yml restart matrix-whatsapp