Bridging between Matrix and Telegram

Updated 23 September 2019

API registration

To establish a bridge between Matrix and Telegram, first register the API:

You will need api_id and api_hash to bridge, as well as MTProto server addresses.

Bot registration

In the Telegram client, go to the BotFather dialog by clicking on the link.

Start a conversation and create your example_bot by running the following commands:


You will see something like that:

Done! Congratulations on your new bot. You will find it at You can now add a description, about section and profile picture for your bot, see /help for a list of commands. By the way, when you've finished creating your cool bot, ping our Bot Support if you want a better username for it. Just make sure the bot is fully operational before you do this.

Use this token to access the HTTP API:
Keep your token secure and store it safely, it can be used by anyone to control your bot.

For a description of the Bot API, see this page:

Remeber what you get as BOT_TOKEN: 123456789:abcdefghijklmniopqrstuvwxyzABCDEFGH.

Type the following messages to give the bot access to discussions in the groups it belongs to:


Activate the bot by going to and sending it a message:


Preparing the LXC container

We recommend that you configure your bridge in a separate container, created as explained in the manual.

Installing software

Install FFmpeg software for the service to work with Telegram videos:

emerge -a media-video/ffmpeg

Create and enable a virtual environment for Python:

mkdir -p /var/calculate/matrix-telegram

cd /var/calculate/matrix-telegram

python3 -m venv .

source bin/activate

Install Matrix-Telegram and the module for operation via SOCKS5 in the virtual environment:

pip install --upgrade mautrix-telegram[all]

pip install PySocks

Copy the example-config.yaml configuration file to config.yaml:

cp example-config.yaml config.yaml

Edit the bridge settings, where:

  • is the address of your Matrix server
  • is the MXID domain
  • http://matrix-telegram:8080 is the bridge address
  • 123456 is the api_id you created earlier
  • secret_hash is the api_hash you created earlier
    # The address that this appservice can use to connect to the homeserver.
    # The domain of the homeserver (for MXIDs, etc).
    address: http://matrix-telegram:8080
    # Public part of web server for out-of-Matrix interaction with the bridge.
    # Used for things like login if the user wants to make sure the 2FA password isn't stored in
    # the HS database.
        # Whether or not the public-facing endpoints should be enabled.
        enabled: false
# Permissions for using the bridge.
# Permitted values:
#   relaybot - Only use the bridge via the relaybot, no access to commands.
#       user - Relaybot level + access to commands to create bridges.
#  puppeting - User level + logging in with a Telegram account.
#       full - Full access to use the bridge, i.e. previous levels + Matrix login.
#      admin - Full access to use the bridge and some extra administration commands.
# Permitted keys:
#        * - All Matrix users
#   domain - All users on that homeserver
#     mxid - Specific user
    "*": "relaybot"
    "": "admin"

    api_id: 123456
    api_hash: secret_hash
    bot_token: bot_token

Add the following settings to be able to use SOCKS5

    # Telethon proxy configuration.
    # You must install PySocks from pip for proxies to work.
        # Allowed types: disabled, socks4, socks5, http
        type: socks5
        # Proxy IP address and port.
        port: 1080
        # Whether or not to perform DNS resolving remotely.
        rdns: true
        # Proxy authentication (optional).
        username: "sockuser"
        password: "secret"

Create a registration file to allow the application to interact with the Matrix server:

python -m mautrix_telegram -g -r registration_telegram.yaml

Copy the registration file to Synapse:

scp registration_telegram.yaml root@synapse:/var/calculate/synapse/

Add the registration file to the Synapse configuration:

    - registration_telegram.yaml

Restart Synapse:

/etc/init.d/synapse restart

Reconfigure the database for the bridge to operate:

alembic upgrade head

Starting the bridge

Create an OpenRC script to manage the Matrix Telegram bridge daemon:

# Copyright 2019 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

name="Matrix-Telegram daemon"
description="Matrix Telegram bridge daemon"
command_args="-m mautrix_telegram -r registration_telegram.yaml"

Edit the privileges:

chmod 755 /etc/init.d/matrix-telegram-bridge

Start the daemon:

/etc/init.d/matrix-telegram-bridge start

Add it to autostart:

rc-update add matrix-telegram-bridge

Integrating Matrix groups with Telegram groups

Getting ID for Telegram group

Invite your Telegram bot to the relevant group:

curl "

{"id":123451234,"is_bot":true,"first_name":"Example bot","username":"example_bot"},"new_chat_member":{"id":123451234,"is_bot":true,"first_name":"Example bot","username":"example_bot"},"new_chat_members":[{"id":123456789,"is_bot":true,"first_name":"Example bot","username":"example_bot"}]}}]}

Getting ID for Telegram channel

Set the bot as a channel administrator and type /id:

curl "

"title":"Example Channel","type":"channel"},"date":1553242405,"text":"/id","entities":[{"offset":0,"length":3,"type":"bot_command"}]}}]}

Room integration

Invite the bot to your room.

Integrate the current room with the Telegram channel or group by its ID, ~~-1001123456789~. Send a message to the common chat room:

!tg bridge -1001123456789
!tg continue