Matrix Messenger Bridges¶
Overview¶
Local Matrix Server (Continuwuity) as a universal message bus for messenger bridges. Each agent can operate its own WhatsApp/Telegram/Signal numbers. Everything is running locally on the server — no external services, no cloud API.
WhatsApp ←→ mautrix-whatsapp ←→ Continuwuity ←→ Comm-Hub
Telegram ←→ mautrix-telegram ←→ (lokal) ←→ Genesis AI
Signal ←→ mautrix-signal ←→ ←→ Frontend
Architecture¶
| Containers | Image | Port (internal) | Task |
|---|---|---|---|
| matrix-conduit | continuity: | 6167 | Matrix Home Server (Rust, ~50 MB RAM) |
| matrix-whatsapp | mautrix/whatsapp:latest | 29318 | WhatsApp Bridge (Multi-Account) |
| matrix-telegram | mautrix/telegram:latest | 29317 | Telegram Bridge (Multi-Account) |
All containers run in theai-network, are **not accessible from outside.
Data flow¶
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¶
If both bridges are active, messages can be bridged between messengers:
Both bridges must be invited in the same matrix space.
Configuration¶
Paths¶
| Path | Contents |
|---|---|
/etc/xynap/matrix/conduit/conduit.toml |
Continuwuity Server Config |
/etc/xynap/matrix/conduit/whatsapp-registration.yaml |
WhatsApp App Service Registration |
/etc/xynap/matrix/conduit/telegram-registration.yaml |
Telegram Appservice Registration |
/etc/xynap/matrix/whatsapp/config.yaml |
WhatsApp Bridge-Config (Reference) |
/etc/xynap/matrix/telegram/config.yaml |
Telegram Bridge Config (Reference) |
/var/lib/xynap/matrix/conduit/ |
Continuwuity Database |
/var/lib/xynap/matrix/whatsapp/ |
WhatsApp Bridge Data + Config |
/var/lib/xynap/matrix/telegram/ |
Telegram Bridge Data + 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— the server communicates exclusively with the local bridges.
Matrix admin account¶
| Field | Value |
|---|---|
| User ID | @admin:matrix.xynap.local |
| Admin-Room | Automatically created at start |
| Access | Only internal via Matrix Client Server API |
WhatsApp Bridge (mautrix-whatsapp)¶
The Bridge uses the official WhatsApp Web Multi-Device Protocol (whatsmeow). Multi-Account: Each matrix user can connect his own WhatsApp number.
Important Config Fields 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)¶
Names anTelegram API Keyfrom my.telegram.org/apps.
Config in/var/lib/xynap/matrix/telegram/config.yaml:
Operation¶
Start/stop containers¶
# 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
Connect WhatsApp Number¶
- Create Matrix User (if not yet available)
- Send a message to the WhatsApp-Bot
@whatsappbot:matrix.xynap.local:login - Scan QR code with WhatsApp → Add a Geraete → Geraet
- Status pruefen: Send
statusto Bot
Each matrix user can connect his own WhatsApp account — the bridge manages several sessions.
Connecting Telegram Account¶
- Write to the Telegram-Bot
@telegrambot:matrix.xynap.local:login - Enter phone number
- Enter Telegram Adjustment Code
- Optional: Enter 2FA password
Appservice administration (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¶
Each agent creates its own 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
The Comm Hub monitors the matrix screen and automatically routes messages to the right agent.
Troubleshooting¶
"as token was not accepted"¶
The Tokens in the Bridge-Config must agree with the app service registration:
# 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
Both must be identical. Restart Bridge after change.
"telegram.api hash not configured"¶
Telegram API opportunities are missing. Create an app on my.telegram.org/appsand enterapi_id+api_hash.
Bridge not reconnected¶
# 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