Telegram Bridge

This guide explains how to use the Telegram bridge from the EMS Integration Manager to integrate your Telegram chats with your EMS server.

It requires your EMS server to have federation on.

The following instructions are done with the Element Desktop on the Element side and on Element iOS for the Telegram side. Element Android should be almost identical to Element Web.

Purchase the Telegram integration

1. Open the EMS control panel at: https://ems.element.io/user/hosting

2. Click the Integrations tab and if you have more than one server, select the server you wish to add the Telegram integration to.
   

3. Click on Telegram Bridge in the list of available Bridges.
   

4. Enter the maximum number of users in Maximum Telegram users.
   Please note: this is the maximum number of Telegram users who actually send messages over the bridge each month. You are only billed for the number of Telegram users who are active. Once you exceed the maximum, then the bridge will be disabled until you increase the maximum.

5. If you wish to allow Matrix users who aren't logged in to Telegram to participate in bridged Telegram chats, follow the steps in this section.

Once you have entered Maximum Telegram users, click Purchase (remember you can always go back to this step and increase the maximum number of Telegram users if you need more in the future).

1. A dialogue will remind you of the price per user and ask if you wish to proceed. Click Purchase if you wish to proceed with the Telegram Integration.
   

2. You will have to wait a few minutes while your host is reprovisioned. Once reprovisioning is finished, you are able to bridge Telegram to your EMS server using your Element client.

Bridge Telegram to your Element account

1. Once the bridge is running, open your Element app. Click on the + next to People.
   

2. Create a Direct Message conversation by typing @telegram:example.ems.host (replace the domain with the one of your homeserver). Then click Go.

3. Wait for the bridge account to join your room.

4. Open Telegram on your mobile device (iOS or Android) and tap on ≡, go to Settings, and then Devices, and then Scan QR Code to start the Telegram QR code scanner. You will use this QR code scanner to scan a QR code displayed by your Element client in the next step.

5. From your Element client, send a login-qr message to the bot to connect to your Telegram account.

6. A QR code will be displayed. Quickly scan the QR code with Telegram on your mobile device.

7. On your Element client, you will see Successfully logged in as <username>.

Sending a message to a Telegram User

To send a message to a Telegram user, you must first be connected to the bridge (see above).

1. On your Element client, open the "Telegram bridge bot" room.

2. Say pm followed by the phone number or username. The phone number must exist in your Telegram contacts.

3. You will be invited to a DM with that user, and can send messages to them.

Bridging Matrix users without a Telegram acccount

By default, a Matrix user will have to connect their Telegram account for their messages to be bridged to Telegram. If you provide a bot token, we will use this bot to relay the messages of any Matrix users to Telegram. (Note: relaying is supported for Telegram groups, but is not yet supported for Telegram channels.)

Follow these steps to register a bot account with Telegram.

1. With your Telegram account, message @BotFather. If talking to BotFather via the bridge using Element, note that all "slash" command messages (eg. /start) sent to BotFather must begin with two slashes instead of one (eg. //start).

2. Create a new bot by sending the message /newbot to BotFather. The created bot will be the Telegram relay bot used by your bridge. Follow the subsequent prompts to give your bot a display name and a username.

3. Wait for BotFather to provide you a bot token.

4. Send the message /setprivacy to BotFather and follow the prompts to set your new bot's privacy settings to "Disabled". This allows your relay bot to bridge all messages sent in a Telegram group, not just messages that mention the bot by name.

5. Open the EMS control panel for your Telegram bridge and enter the token you received from BotFather in the "Bot token" field, then wait for the page to notify you when your bridge is ready.

6. In your Element client, view your DM with the Telegram bridge bot and send the ping-bot command. The bot should respond with the ID of your relay bot in Matrix, which indicates that the relay bot has been set up correctly.

7. In your Element client, invite the Matrix relay bot to any room that bridges a Telegram group that should relay Matrix users' messages to Telegram. A convenient way to do so is to send a message of !tg ping-bot in such a room (which will be intercepted by the bridge bot & won't appear in Telegram), wait for the bridge bot to respond with a "pill" of the relay bot's Matrix ID, click on the pill, and then click "Invite" on the sidebar that appears.

8. In Telegram, confirm that your Telegram relay bot has joined the group. If it hasn't, you may manually invite your bot to the group (as long as you have permissions to do so) by viewing the group's details, selecting "Add Members", and entering the username of your relay bot that you chose in step 2.