Connect Matrix to WhatsApp, Telegram, and Discord with Separate Bridges

To connect WhatsApp, Telegram, and Discord, run three separate bridges, register each as an application service, and sign in through its own flow. Success means each bot reports an authenticated session and test messages travel both ways through portal rooms; a bot merely appearing online is not enough.

This is for an administrator of a homeserver that permits application services. You cannot add a self-hosted bridge to matrix.org unless its administrators offer one; use a server you control or an available hosted bridge. Project documentation was checked October 10, 2026.

1. Decide what you are connecting and prepare the server

These are three separate services, each with its own configuration, registration, database, and login. mautrix mainly uses puppeting: messages travel through your linked remote account and appear in Matrix as that account. A relay bot is different; choose it only if you want a shared bot identity rather than your personal account.

You need an application-service-capable homeserver, admin access, and network connectivity to each bridge. Docker is documented. Give each bridge its own data directory and choose a maintained version tag; mautrix notes that latest may track the latest commit rather than a release.

Use a separate database per bridge; a PostgreSQL server may be shared, but the database itself must not be shared with another bridge or Synapse. SQLite is an option for small instances. Decide about end-to-bridge encryption before login because enabling it later for existing portal rooms is difficult.

Terminal directory listing with separate mautrix-whatsapp, mautrix-telegram, and mautrix-discord folders, each showing its own configuration and database file.
Keep each bridge’s configuration and database in its own working directory before starting the containers.

2. Configure and register all three application services

  1. Generate each bridge’s initial configuration. Follow the Docker setup page for that bridge and run its container once with its own data directory mounted. Edit the generated configuration before starting it normally. Fill in the homeserver domain and address, bridge address, database URI, and permissions. These values are specific to your deployment; do not paste example secrets into production.
  2. Use container-reachable addresses. When Synapse and the bridges share a Docker network, the bridge’s homeserver address can use Synapse’s service name, such as http://synapse:8008. The application-service address must point back to that bridge’s service name and listening port. localhost inside a bridge container points to that same container, not Synapse or another bridge, so it usually breaks communication. If the homeserver is outside Docker, publish or route the required bridge port instead.
  3. Generate and install one registration file per bridge. Run each bridge’s setup command to generate its registration YAML, then place all three files where Synapse can read them. In homeserver.yaml, add their paths under app_service_config_files, for example:
app_service_config_files:
  - /data/appservices/mautrix-whatsapp-registration.yaml
  - /data/appservices/mautrix-telegram-registration.yaml
  - /data/appservices/mautrix-discord-registration.yaml

Mount the registration files inside the Synapse container if Synapse runs in Docker. Restart Synapse after editing the list. A YAML typo, wrong path, unreadable mount, or mismatched bridge address can prevent registration or stop Synapse from starting. If you change registration-related bridge settings later, regenerate the relevant registration file and restart Synapse again.

Code editor showing Synapse homeserver.yaml with three separate application service registration paths for WhatsApp, Telegram, and Discord.
Synapse needs a separate readable registration path for each bridge, followed by a homeserver restart.
Container status panel listing Synapse and three mautrix bridge containers as running on a shared Matrix network.
Check that Synapse and all three bridge containers are running on a network where their service names resolve.

3. Add the service-specific credentials and sign in

WhatsApp

Start mautrix-whatsapp and open a Matrix direct message with its bridge bot, typically @whatsappbot:your.server. Send login qr, then scan the QR code from WhatsApp’s Linked devices screen on your phone. Wait for the bot to confirm authentication; the bridge documentation says portal rooms may take about a minute to appear. WhatsApp is linked as a device, so this is not a standalone cloud account. The bridge docs say linked devices disconnect if the phone remains offline for more than two weeks. If you cannot keep the phone active, consider whether this bridge meets your reliability needs before relying on it for important chats.

Telegram

Before Telegram login, create an API application at my.telegram.org/apps and put its api_id and api_hash in mautrix-telegram’s configuration. These API values let the bridge connect to Telegram’s API; they do not authenticate a Telegram account by themselves. Then message @telegrambot:your.server and use login qr, scanning it from Telegram’s mobile app under Settings, Devices, and Link Desktop Device. The code option may be delivered to an existing Telegram session rather than by SMS, and the bridge can prompt for your two-step verification password. Check the bridge’s backfill settings before login if importing older messages matters; changing expectations after portal rooms are created may be too late.

Discord

For a server, use a dedicated Discord bot, not automation of your personal account: Discord forbids self-bots and may terminate accounts. Create an application and bot in the Developer Portal, enable only the privileged intents the bridge requires and your app can obtain, then invite it with the OAuth2 bot scope and minimum channel permissions. Intent access is policy-controlled; without needed message-content or member access, some functions may not work. In Matrix, DM @discordbot:your.server and follow mautrix-discord’s bot-token login instructions. A bot does not provide the same personal-DM access as a user-account bridge.

A bridge configuration editor showing a Synapse service address, a mautrix-whatsapp service address, and a distinct bridge database name.
Review the service hostname, bridge listener, and unique database details in each bridge’s own configuration.

4. Test delivery, then adjust only what the result shows

DM each bridge bot and confirm an authenticated status. In one portal room per service, send a test message from Matrix and reply from the remote app. Verify both arrive in the right room. For groups or Discord channels, first confirm the bridge account is present and has read/post permissions. A successful login alone does not prove delivery.

If a bot is silent, check its logs for missing values, database errors, or homeserver connectivity. If login works but rooms do not appear, check portal and backfill settings. For missing Discord channel messages, check bot membership, permissions, and intent access. If Synapse fails to start, verify YAML indentation and readable registration-file mounts.

Feature support varies by bridge version and account type; calls, reactions, encrypted chats, media, and history import may differ or be unsupported. Check each bridge’s current feature list before relying on it as your only access point. Restrict access to registration files and credentials, back up bridge data securely, and revoke a linked session or token if exposed.

Use the current mautrix Docker instructions, registration guide, configuration reference, and the WhatsApp, Telegram, and Discord authentication pages for version-specific commands. Review Discord’s self-bot policy.

Leave a Comment

Clean Up Old Synapse Messages and Media Without Losing Data

Use Synapse’s history and media purge APIs or retention settings to remove stale data safely, then verify completion and disk-space recovery.

Build a Matrix Echo Bot in Python with Simple-Matrix-Bot-Lib

Build a Matrix Echo Bot in Python with Simple-Matrix-Bot-Lib

Install the current library, connect a dedicated Matrix account, and run a small !echo bot with safer credential handling and a clear test.

Connect Matrix to WhatsApp, Telegram, and Discord with Separate Bridges

Connect Matrix to WhatsApp, Telegram, and Discord with Separate Bridges

Set up three mautrix bridges with separate registrations, logins, and tests—and avoid Docker networking, account-policy, and sync surprises.

Reclaim Synapse Media Disk Space Without Breaking Shared Files

Find what is filling Synapse storage, set safe media retention, and purge remote cache without deleting files directly from disk.

Deactivate Inactive Matrix Users Without Deleting Room History

Deactivate Inactive Matrix Users Without Deleting Room History

Review device activity, deactivate confirmed inactive Synapse accounts through the Admin API, and learn what the optional erase flag actually removes.

Reduce PostgreSQL Memory Pressure in Matrix Synapse

Find whether PostgreSQL memory comes from query work, shared buffers, connections, or maintenance, then make targeted Synapse-safe changes.

Why Matrix Synapse Room Joins Are Slow—and What to Check

Why Matrix Synapse Room Joins Are Slow—and What to Check

Trace slow Matrix room joins to one remote homeserver, federation backoff, local database load, or an outbound sender queue before changing Synapse settings.

Close Matrix Sign-Ups or Require Invite Tokens on Synapse

Stop open account creation on a self-hosted Synapse server, or keep sign-ups invite-only with limited-use registration tokens.

Element Session Identity Warning: Verify Your Login Safely

Clear Element's unverified-session warning using a trusted device or recovery key, with checks that protect your encrypted chat history.

Stop ownCloud File Lock Timeouts with the Right Backend

Distinguish database lock contention from expired WebDAV locks, then choose and configure the right ownCloud 10 fix.