TG Media Downloader Bot 🤖

A simple MTProto-based bot that can download various types of media (>10MB) on a local storage

Table of Contents

1. 📖 About The Project
   • Why should I use a MTProto bot?
2. ⚙️ Getting Started
   • Installation
   • Usage
   • Generating Telegram API keys
   • Creating a Telegram Bot
   • TO-DO
3. 💫 Contributing
4. 🤝 Support
5. ⚠️ License
6. 🛠️ Built With

📖 About The Project

A telegram bot based on Pyrogram that downloads on a local storage the following media files: animation, audio, document, photo, video, voice.

The bot is inspired from the Telethon-based bot by rodriguezst.

(back to top)

Why should I use a MTProto bot?

MTProto clients connect directly to Telegram’s servers, which means there is no HTTP connection, no “polling” or “web hooks”. This means less overhead, since the protocol used between you and the server is much more compact than HTTP requests with responses in wasteful JSON.

Since there is a direct connection to Telegram’s servers, even if their Bot API endpoint is down, you can still have connection to Telegram directly.

Using a MTProto client, you are also not limited to the public API that they expose, and instead, you have full control of what your bot can do.

HTTP Bots can't download file bigger than 10mb meanwhile MTProto can download files of 1.5~4GB!

(back to top)

⚙️ Getting Started

The bot requires the following parameters to work:

Parameter	Role
TG_API_ID	Telegram API ID obtained via developer settings (see here)
TG_API_HASH	Telegram API HASH obtained via developer settings (see here)
TG_BOT_TOKEN	Telegram Bot Token obtained via BotFather (see here)
TG_MAX_PARALLEL [OPTIONAL]	Maximum number of parallel downloads allowed (default: 4) A big number can cause flood blocks
TG_DL_TIMEOUT [OPTIONAL]	Maximum time (in seconds) to wait for a download to complete (default: 5400) In case of timeout the download is aborted and a error is triggered
TG_DOWNLOAD_PATH	Download folder on the local storage/docker mount where the files will be downloaded The files will appear inside the folder only after download completation
TG_AUTHORIZED_USER_ID	List separated by comma of authorized users' id, you can get them using the userinfobot It can't be empty

(back to top)

Installation

The bot can be executed inside a Docker container or directly on your PC/Server OS.

Docker

To dockerize the bot, just pull or build the image and provide the required parameters.

An official GitHub Package is available here.

Make sure that the download path is a mounted as a volume to allow the host system to access the downloaded files.

Barebone

To run the bot directly on your PC/Server OS, do the following steps:

1. Make sure to have Python 3.10+ installed on your system;

2. Create a folder anywhere on your pc and clone the repository there:

   git clone https://github.com/LightDestory/TG_MediaDownloader

3. Install the requirements (create a venv if you don't want to dirty the system packages):

   pip install -r requirements.txt

4. Execute the bot and follow the wizard to provide the requires parameters:

   python ./tg_downloader.py

(back to top)

Usage

After the setting up process, the bot is ready to use. Send/forward any supported media to the bot to start the download on your local storage.

The bot supports the following commands:

Command	Role
/start	Initial command (invoked by Telegram) when you start the chat with the bot for the first time.
/help	Gives you the available commands list.
/about	Gives you information about the project.
/abort	Cancel all the pending downloads.
/status	Gives you the current configuration.
/usage	Gives you the usage instructions.
/set_download_dir	Sets a new download dir.
/set_max_parallel_dl	Sets the number of max parallel downloads.

(back to top)

Generating Telegram API keys

To make the bot work you must provide your own API ID and hash:

1. Go to My Telegram and login with your phone number;
2. Click under API Development tools;
3. A 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 ID and API Hash are secrets and Telegram won't let you revoke it. Don't post it anywhere!

(back to top)

Creating a Telegram Bot

1. Open a conversation with @BotFather in Telegram

2. Use the /newbot command to create a new bot. The BotFather will ask you for a name and username, then it will generate an authorization token for your new bot.

   • The name of your bot is displayed in contact details and elsewhere.
   • The Username is a short name, to be used in mentions and telegram.me links. Usernames are 5-32 characters long and are case-insensitive, but may only include Latin characters, numbers, and underscores. Your bot`s username must end in ‘bot’, e.g. ‘tetris_bot’ or ‘TetrisBot’.
   • The token is a string along the lines of 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw that is required to authorize the bot and send requests to the Bot API. Keep your token secure and store it safely, it can be used by anyone to control your bot.

(back to top)

TO-DO

• It runs
• It downloads supported media
• Use a fallback for missing metadata
• Allow custom names for un-named files instead of file_unique_id
• On the fly configuration changes
• Improve error handling related to Telegram's service

(back to top)

💫 Contributing

If you are interested in contributing, please refer to Contributing Guidelines for more information and take a look at open issues. Ask any questions you may have and you will be provided guidance on how to get started.

Thank you for considering contributing.

(back to top)

🤝 Support

If you find value in my work, please consider making a donation to help me create, and improve my projects.

Your donation will go a long way in helping me continue to create free software that can benefit people around the world.

(back to top)

⚠️ License

The content of this repository is distributed under the GNU GPL-3.0 License. See LICENSE for more information.

(back to top)

🛠️ Built With

• Python
• Pyrogram

(back to top)