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:

/start
/newbot
example_bot

You will see something like that:

Done! Congratulations on your new bot. You will find it at t.me/example_bot. 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:
123456789:abcdefghijklmniopqrstuvwxyzABCDEFGH
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: https://core.telegram.org/bots/api

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:

/setprivacy
@example_bot
Disable

Activate the bot by going to ~t.me/example_bot~ and sending it a message:

/start

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:

Create and enable a virtual environment for Python:

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

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

Edit the bridge settings, where:

• https://matrix.example.org is the address of your Matrix server
• matrix.example.org 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

homeserver:
    # The address that this appservice can use to connect to the homeserver.
    address: https://matrix.example.org
    # The domain of the homeserver (for MXIDs, etc).
    domain: matrix.example.org
appservice:
    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.
    public:
        # 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
permissions:
    "*": "relaybot"
    "@admin:matrix.example.org": "admin"

telegram:
    api_id: 123456
    api_hash: secret_hash
    bot_token: bot_token

Add the following settings to be able to use SOCKS5 1.2.3.4:1080:

telegram:
    # Telethon proxy configuration.
    # You must install PySocks from pip for proxies to work.
    proxy:
        # Allowed types: disabled, socks4, socks5, http
        type: socks5
        # Proxy IP address and port.
        address: 1.2.3.4
        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:

Copy the registration file to Synapse:

Add the registration file to the Synapse configuration:

app_service_config_files:
    - registration_telegram.yaml

Restart Synapse:

Reconfigure the database for the bridge to operate:

Starting the bridge

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

#!/sbin/openrc-run
# 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=/var/calculate/matrix-telegram/bin/python3
command_args="-m mautrix_telegram -r registration_telegram.yaml"
directory=/var/calculate/matrix-telegram
pidfile="/run/matrixtelegram.pid"
command_background=true

Edit the privileges:

Start the daemon:

Add it to autostart:

Integrating Matrix groups with Telegram groups

Getting ID for Telegram group

Invite your Telegram bot to the relevant group:

{"ok":true,"result":[{"update_id":123451234,
"message":{"message_id":12345,"from":{"id":123451234,"is_bot":false,"first_name":"User","username":"Username"},
"chat":{"id":-100123456789,
"title":"Groupname","username":"calculate_talk","type":"supergroup"},
"date":1553239850,"new_chat_participant":
{"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:

"channel_post":{"message_id":123,
"chat":{"id":-1001123456789,
"title":"Example Channel","type":"channel"},"date":1553242405,"text":"/id","entities":[{"offset":0,"length":3,"type":"bot_command"}]}}]}

Room integration

Invite @telegrambot:matrix.example.org 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