Signing In as a Bot Account

You can also use Telethon for your bots (normal bot accounts, not users). You will still need an API ID and hash, but the process is very similar:

from telethon.sync import TelegramClient

api_id = 12345
api_hash = '0123456789abcdef0123456789abcdef'
bot_token = '12345:0123456789abcdef0123456789abcdef'

# We have to manually call "start" if we want an explicit bot token
bot = TelegramClient('bot', api_id, api_hash).start(bot_token=bot_token)

# But then we can use the client instance as usual
with bot:

To get a bot account, you need to talk with @BotFather.

Telethon Editing the Code

This is a little introduction for those new to Python programming in general.

We will write our code inside, so you can use any text editor that you like. To run the code, use python3 from the terminal.


Don’t call your script! Python will try to import the client from there and it will fail with an error such as “ImportError: cannot import name ‘TelegramClient’ …”.

Telethon Signing In

Before working with Telegram’s API, you need to get your own API ID and hash:

  1. Login to your Telegram account with the phone number of the developer account to use.
  2. Click under API Development tools.
  3. Create new application window will appear. Fill in your application details. There is no need to enter any URL, and only the first two fields (App title and Short name) can currently be changed later.
  4. Click on Create application at the end. Remember that your API hash is secret and Telegram won’t let you revoke it. Don’t post it anywhere!


This API ID and hash is the one used by your application, not your phone number. You can use this API ID and hash with any phone number or even for bot accounts.

Telethon Optional Dependencies

If cryptg is installed, the library will work a lot faster, since encryption and decryption will be made in C instead of Python. If your code deals with a lot of updates or you are downloading/uploading a lot of files, you will notice a considerable speed-up (from a hundred kilobytes per second to several megabytes per second, if your connection allows it). If it’s not installed, pyaes will be used (which is pure Python, so it’s much slower).

If pillow is installed, large images will be automatically resized when sending photos to prevent Telegram from failing with “invalid image”. Official clients also do this.

If aiohttp is installed, the library will be able to download WebDocument media files (otherwise you will get an error).

If hachoir is installed, it will be used to extract metadata from files when sending documents. Telegram uses this information to show the song’s performer, artist, title, duration, and for videos too (including size). Otherwise, they will default to empty values, and you can set the attributes manually.


Some of the modules may require additional dependencies before being installed through pip. If you have an apt-based system, consider installing the most commonly missing dependencies (with the right pip):

apt update
apt install clang lib{jpeg-turbo,webp}-dev python{,-dev} zlib-dev
pip install -U --user setuptools
pip install -U --user telethon cryptg pillow

Thanks to @bb010g for writing down this nice list.

Verification Telethon

To verify that the library is installed correctly, run the following command:

python3 -c "import telethon; print(telethon.__version__)"

The version number of the library should show in the output.

Installing Development Versions

If you want the latest unreleased changes, you can run the following command instead:

python3 -m pip install --upgrade


The development version may have bugs and is not recommended for production use. However, when you are reporting a library bug, you should try if the bug still occurs in this version.