synapse-docker-bridges/config/mautrix-telegram

Telegram Bridge Setup Guide

This guide will help you set up the Telegram bridge for your Synapse Matrix server.

Prerequisites

Before starting, ensure that:

• Synapse is properly configured and running.
• The telegram database was created during the initial setup.
• You have your domain name ready.
• You have your Telegram API credentials (we'll cover this below).

Obtaining Telegram API Credentials

Before configuring the bridge, you'll need to obtain API credentials from Telegram:

1. Visit my.telegram.org and log in.
2. Go to "API development tools".
3. Create a new application if you haven't already.
4. Note down your api_id and api_hash - you'll need these later.

Setup Steps

1. Navigate to the Telegram configuration directory:

cd config/mautrix-telegram

2. Generate the initial configuration file:

docker run --rm -v `pwd`:/data:z dock.mau.dev/mautrix/telegram

3. Edit the generated config.yaml file. You may need administrative privileges (sudo) to edit this file.

Required Configuration Changes

Make the following modifications to your config.yaml:

Homeserver Settings

homeserver:
    address: http://monolith:8008  # Internal Docker network address
    domain: your.domain.com        # Replace with your actual domain

Appservice Settings

appservice:
    address: http://telegram:29317  # Internal bridge address
    hostname: 0.0.0.0              # Listen on all interfaces

Bridge Settings

bridge:
    permissions:
        '*': relaybot
        public.your.domain.com: user     # Replace with your domain
        your.domain.com: full
        "@yourusername:your.domain.com": admin  # Replace with your Matrix ID

    # Add your Telegram API credentials
telegram:
    api_id: 123456      # Replace with your api_id
    api_hash: "abcdef"  # Replace with your api_hash

Database Connection

Update the database URI to use the Telegram-specific database:

# Original:
# postgres://synapse:password@postgres/synapse?sslmode=disable

# Modified (note 'telegram' database name):
postgres://synapse:password@postgres/telegram?sslmode=disable

4. Generate the registration file:

docker run --rm -v `pwd`:/data:z dock.mau.dev/mautrix/telegram

5. Configure Synapse to use the Telegram bridge by editing config/synapse/homeserver.yaml:

app_service_config_files:
- "/etc/telegram/registration.yaml"

6. Start the bridge service:

docker compose up -d mautrix-telegram

7. Restart Synapse to load the new bridge configuration:

docker compose restart monolith

Verifying the Setup

Check if the bridge is running:

docker compose logs mautrix-telegram

You should see messages indicating the bridge has started successfully. If the configuration files aren't present, the service will remain stopped - this is normal and prevents unnecessary restarts.

Using the Bridge

1. Start a chat with @telegrambot:your.domain.com in your Matrix client.
2. Send the command !tg login to start the login process.
3. Follow the bot's instructions to:
   • Provide your phone number.
   • Enter the verification code sent to your Telegram app.
   • Complete two-factor authentication if enabled.

Double Puppeting

Double puppeting allows messages sent from Telegram to appear as coming from your Matrix account. To enable it:

1. You'll need the access token that was displayed when you created your Matrix user with the create-user.sh script.
2. Start a private chat with @telegrambot:your.domain.com.
3. Send the command: login-matrix (without the access token).
4. When prompted, send your access token in a separate message. (This is the access token that was saved from create-user.sh).
5. The bot should confirm successful double puppeting setup.

Note: If you've lost your access token, you can generate a new one using Element or another Matrix client in Settings > Help & About > Access Token.

Troubleshooting

1. Bridge Not Starting

   • Verify that both config.yaml and registration.yaml exist.
   • Check file permissions.
   • Review logs with docker compose logs mautrix-telegram.
   • Verify API credentials are correct.

2. Login Issues

   • Confirm your phone number format (including country code).
   • Check if your account has 2FA enabled.
   • Verify API credentials are correct.

3. Message Delivery Problems

   • Verify bridge service is running.
   • Check bridge permissions in config.
   • Ensure Telegram session is still valid.

Next Steps

• Proceed to set up the Discord Bridge.

For more detailed information about bridge features and configuration options, visit the mautrix-telegram documentation.