Matrix Telegram Bridge

Telegram is the well known chat app which started as the main competitor to Whatsapp and it's finally gaining some traction. Most known for it's piracy and porn angles, it's getting more and more popular to replace Whatsapp itself also for private chats.

Telegram can be easily and fully bridged with Matrix using the Mautrix-Telegram bridge here.

At the time of writing this page, a full rewrite in Go of the bridge is undergoing but not yet officially released, so i will show you how to install the older python-based bridge. When the rewrite will be complete, the instructions will be a mirror of the ones for the Whatsapp and Signal bridges, which have already migrated to Go.

I asusme you are installing the bridge directly together with the Matrix server, as user conduwuit.

Create a subfolder in which you need to initialize a Python venv inside (see PIP):

su - conduwuit
mkdir mautrix-telegram
cd mautrix-telegram
# Enable PIP like described in the link above:
# - create ~/.config/pip/pip.conf
# - add ~/.local/bin to the .bashrc
python -m venv . # Note the dot at the end!
source ./bin/activate
# Now set "include-system-site-packages = true" in pyvenv.cfg
# Install:
pip install --upgrade mautrix-telegram[all]

Please follow the instructions to enable PIP venvs as described in the link above.

This will install the bridge itself.

First of all, you cannot create a new telegram account from the bridge, you need to do so from the official telegram app, it's the one and only way.

Now, assuming you have a Telegramn account, you need to create API keys to connect to Telegram. Go to this page and login with your phone number and the code that will be delivered to your telegram account.

From the page that pops up, generate and take note of api_id and api_hash as you will need to configure the bot. You should also give a name like MatrixBot or whatever you like.

Unfortunately, the python bridge doesn't generate the configuration file skeleton automatically and you need to download the example one from here and save it to the conduwuit data folder:

cd /data/conduwuit
wget -O /data/conduwuit/mautrix-telegram-config.yaml https://raw.githubusercontent.com/mautrix/telegram/refs/heads/master/mautrix_telegram/example-config.yaml

For an organizational reason, i prefer to keep all the stuff that needs to be backupped into /data/conduwuit instead of under /data/daemons/conduwuit.

This file is huge, here are the most relevant changes needed:

config.yaml

    address: https://chat.mydomain.com
    domain: chat.mydomain.com
    verify_ssl: true
    database: sqlite:/data/conduwuit/mautrix-telegram.db # place the database into the /data/conduwuit folder
telegram:
    # Get your own API keys at https://my.telegram.org/apps
    api_id: << put your id here >>
    api_hash: << put your hash >>
    # (Optional) Create your own bot at https://t.me/BotFather
    bot_token: disabled
permissions:
  "*": "relaybot"                      # non-local users can only see messages
  "chat.mydomain.com": "full"          # full access to all local users
  "@myself:chat.mydomain.com": "admin" # who can admin the bot
  
  encryption:
    # Whether to enable encryption at all. If false, the bridge will not function in encrypted rooms.
    allow: true

  double_puppet_server_map:
        example.com: https://chat.gardiol.org
  double_puppet_allow_discovery: false
  login_shared_secret_map:
      chat.gardiol.org: << here the double pupper as_token >>

More details on configuration can be found here. To setup double-puppeting, see here.

I choose to use SQLite as database because i only have a few users and don't want to spin a PostreSQL instance for that.

At this point you need to register the bridge with the Matrix server.

First of all, generate the registration.yaml file:

python -m mautrix_telegram -g -c /data/conduwuit/mautrix-telegram-config.yaml

Then perform the actual appservice registration, see here.

You need to create the telegrambot user, again from the admin chat. this step could be skipped if the user has been already created, it seems to be hit and miss with these Python bridges.

In case the user is missing, from the Matrix server admin chat type:

!admin users create-user telegrambot

Good! Now you can run the bridge:

python -m mautrix_telegram -c /data/conduwuit/mautrix-telegram-config.yaml

If all is well, your bridge should be up and running now.

To login into telegram you need to:

• Start a chat with @telegrambot:chat.mydomain.com
• type “login”
• when prompted, type your telegram registered phone number with country code
• when prompted, type the code you received in telegram to authorize the login
• when prompted, type your 2FA password (if enabled in telegram)

You will start seeing your telegram chats appear in Matrix now! It takes time, even hours, and also most chats will only appear the first time the other person messages you.

General documentation on the Telegram bot can be found here.

To manage animated sticker here

Since i use OpenRC, simply drop the following script to /etc/init.d:

/etc/init.d/conduwuit-telegram

#!/sbin/openrc-run
# Copyright 2025 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

name="conduwuit telegram bridge"
description="Conduwuit Telegram Matrix Bridge"
pidfile="/run/conduwuit-telegram.pid"
command_background=true
command="/data/daemons/conduwuit/mautrix-telegram/bin/python"
command_args=" -m mautrix_telegram -c /data/conduwuit/mautrix-telegram-config.yaml"
command_user="conduwuit:conduwuit"
output_log="/var/log/conduwuit/conduwuit-telegram.log"
output_err="/var/log/conduwuit/conduwuit-telegram.log"

start_pre() {
        cd /data/daemons/conduwuit/mautrix-telegram
}

depend() {
        need net
}

Make it executable and add to the proper runlevel:

chmod +x /etc/init.d/conduwuit-telegram
rc-update add conduwuit-telegram default