Logging in

As logging in requires you to send the phone code and possibly also your 2FA password, make sure to run the commands in a management room (i.e. a room with no other users than you and the appservice bot).

If you have 2-factor auth enabled or if you are logging in with a bot token, you should use the web login, as otherwise the homeserver database will likely contain your password/token in plaintext form.

Start a chat with the bridge bot (@telegrambot:example.com by default)
Initiate the login process with login.
The bot should tell you to use the web interface or login in-Matrix. If you have enabled both login modes in the config, the bot will give you both options.
Choose the login method you want and follow the instructions under that heading, then go to the "Finally" section.

Send your phone number to the room.
The bot should prompt you to send your auth code to the room: send it once it does.
If you have two-factor authentication enabled, again wait for the prompt and then send your password to the room.

New in version 0.2.0

Click the link sent by the bot, enter your phone number and click "Request code".
Enter your code and click "Sign in".
If you have two-factor authentication enabled, enter your password and click "Sign in" again.

Bot token

New in version 0.3.0

You can also log in with your own relay bot. This is more limited than real accounts, but it means you can appear as yourself on Telegram without giving the bridge access to your real account.

In-Matrix

Send your bot token to the room.

Web

Click the link sent by the bot and click "Use bot token".
Enter your bot token and click "Sign in".

Finally: If all went well, the bot should inform you of a successful login and the bridge should start creating portal rooms for all your Telegram groups and invite you to them. The bridge won't automatically create rooms for private chats: see "Private messages" at the bottom of Creating and managing chats

Double puppeting

New in version 0.3.0

Changed in version 0.9.0: double puppeting is no longer limited to users on the same homeserver as the bridge

When you are logged in with your Telegram account, you can replace the Matrix ghost of your Telegram account with your Matrix account. This is called double-puppeting: the bridge will puppet (have control of) both your Telegram account and your Matrix account. When you do so, messages that you send from other Telegram clients will be sent from your Matrix account.

Also, in servers that don't support MSC2409 (i.e. Synapse before v1.22), it is the only way to enable bridging of ephemeral events, such as presence, typing notifications and read receipts.

Since version 0.7.0, you can also enable automatic double puppeting using shared secret login (see bridge.login_shared_secret_map or bridge.login_shared_secret before 0.9.0 in the config). This way the login is completely transparent to users.

Ask for login methods with login-matrix
Either send your access token to the room, or click the link sent by the bot and fill the login form.
After logging in, the default Matrix ghost of your Telegram account should leave rooms, and your account should join all rooms the ghost was in.

Registering

New in version 0.2.0

As with login, you shouldn't register in a room with other users. Registering via the web UI is not currently possible.

Please note that Telegram might not like users who register using 3rd party clients. To avoid getting banned, it is recommended to register with a real phone number (i.e. not an online SMS service) using an official client (web/desktop/android/ios)

Registration has not been tested, but it should work like this:

Request a Telegram auth code with register <phone number> <full name for Telegram>
The bot should prompt you to send your auth code to the room: send it once it does.
The bot should inform you of a successful registration, after which you can join groups with your own name or start private chats.

Logging out

Simply run the logout management command.

Wiki deprecated

mautrix-telegram docs are now on docs.mau.fi