What is Pyrogram?
Pyrogram is a modern Python library used to interact with Telegram. It allows developers to build both user clients and bot clients easily. The library is known for its clean syntax, speed, and flexibility, which makes it beginner-friendly.
Pyrogram with MTProto
Pyrogram works directly with Telegram’s MTProto protocol. This is the same protocol used by official Telegram apps.
What is MTProto?
MTProto is Telegram’s low-level communication protocol. It allows full access to Telegram features, including those that are not available in the Bot API.
MTProto vs Bot API
| Feature | MTProto | Bot API |
|---|---|---|
| Access level | Full Telegram features | Limited |
| Speed | Faster | Moderate |
| Account type | User + Bot | Bot only |
| Message control | Advanced | Basic |
| Restrictions | Fewer | More |
Advantages of Pyrogram MTProto
- Full Telegram functionality
- Works with both user accounts and bots
- Faster message handling
- Fewer Telegram restrictions
- Clean and readable syntax
If you need powerful automation, MTProto with Pyrogram is usually the better choice.
Simple Echo Bot Implementation
Let us build a basic echo bot that replies with the same message sent by the user.
Step 1: Install Pyrogram
pip install pyrogram tgcryptoStep 2: Create Telegram Bot
- Open Telegram
- Search for BotFather
- Create a new bot
- Copy the bot token
Step 3: Basic Echo Bot Code
from pyrogram import Client, filters
API_ID = 123456
API_HASH = "your_api_hash"
BOT_TOKEN = "your_bot_token"
bot = Client(
"echo-bot",
api_id=API_ID,
api_hash=API_HASH,
bot_token=BOT_TOKEN
)
@bot.on_message(filters.text & filters.private)
async def echo(client, message):
await message.reply_text(message.text)
bot.run()How it works
Clientcreates the bot instancefilters.textcaptures text messages- The bot replies with the same text
Commands Implementation
Now, let us add some basic commands.
Start Command
@bot.on_message(filters.command("start"))
async def start_cmd(client, message):
await message.reply_text(
"Hello. I am a simple Pyrogram bot."
)Help Command
@bot.on_message(filters.command("help"))
async def help_cmd(client, message):
await message.reply_text(
"Available commands:\n/start\n/help\n/about"
)About Command
@bot.on_message(filters.command("about"))
async def about_cmd(client, message):
await message.reply_text(
"This bot is built using Pyrogram."
)Buttons and Callbacks
Inline buttons allow users to interact with the bot without sending new messages. Each button sends a small piece of data called callback_data back to the bot.
Creating Buttons
from pyrogram.types import InlineKeyboardMarkup, InlineKeyboardButton
@bot.on_message(filters.command("start"))
async def start_cmd(client, message):
buttons = InlineKeyboardMarkup(
[
[InlineKeyboardButton("Help", callback_data="help_cb")],
[InlineKeyboardButton("About", callback_data="about_cb")]
]
)
await message.reply_text(
"Welcome. Choose an option:",
reply_markup=buttons
)Handling Callbacks
When a user clicks the button, the on_callback_query handler receives this data, and the bot can respond accordingly. This makes bots feel more like interactive applications rather than simple chat responders.
@bot.on_callback_query()
async def callbacks(client, callback_query):
if callback_query.data == "help_cb":
await callback_query.message.edit_text(
"This is the help section."
)
elif callback_query.data == "about_cb":
await callback_query.message.edit_text(
"About this bot built with Pyrogram."
)Filters and Decorators
Filters in Pyrogram are used to control which messages your bot should process. Instead of checking conditions manually inside your function, filters allow Pyrogram to route updates automatically to the correct handler.
For example, filters.text ensures the handler runs only for text messages, while filters.command("start") triggers only when the user sends the /start command. You can also combine filters using & (and), | (or) to create precise conditions.
Common Filters
filters.textfilters.privatefilters.command("start")filters.photofilters.group
Example
@bot.on_message(filters.photo)
async def photo_handler(client, message):
await message.reply_text("Nice photo")
Now, let’s explore decorators in Pyrogram. Pyrogram uses decorators to handle updates. The @bot.on_message() decorator tells Pyrogram to register the function as an update handler. Whenever a message matches the given filter, Pyrogram automatically calls that function.
This decorator-based approach keeps the code clean and readable, since you do not need to write manual polling or routing logic.
Plugins in Pyrogram
Plugins in pyrogram help you organize large bots into multiple files. This keeps the project clean and maintainable. Plugins help you split a large bot into multiple files for better organization. Instead of writing all handlers in one file, each feature like start, help, admin commands, can live in its own plugin file.
When you enable the plugins option in the Client, Pyrogram automatically loads all handler files from the specified folder. This approach improves maintainability and is strongly recommended for medium and large bots.
Folder Structure
bot/
├── bot.py
└── plugins/
├── start.py
├── help.pyEnable Plugins
bot = Client(
"echo-bot",
api_id=API_ID,
api_hash=API_HASH,
bot_token=BOT_TOKEN,
plugins=dict(root="plugins")
)Example Plugin File
plugins/start.py
from pyrogram import Client, filters
@Client.on_message(filters.command("start"))
async def start_cmd(client, message):
await message.reply_text("Hello from plugin")Now Pyrogram will automatically load this plugin.
Conclusion
Pyrogram is a powerful and beginner-friendly library for building Telegram bots using MTProto. It provides more control than the Bot API and supports advanced automation features.
However, it is important to note that Pyrogram has been discontinued, so new projects should carefully consider long-term maintenance and alternatives. Still, many developers continue to use it for existing projects because of its simplicity and power.
FAQ
1. Is Pyrogram free to use?
Yes. Pyrogram is an open-source Python library and is completely free to use for both personal and commercial projects.
2. Do I need BotFather to create a Pyrogram bot?
Yes, if you are building a bot account. You must create the bot using BotFather and use the bot token in your code. For userbots, BotFather is not required.
3. What is the difference between a userbot and a bot in Pyrogram?
A userbot runs using a normal Telegram user account and has more access to Telegram features. A bot runs using a bot token and follows Telegram Bot API limitations.
4. Can I run multiple plugins in Pyrogram?
Yes. Pyrogram automatically loads all plugin files from the plugins folder when you enable the plugins parameter in the Client. This makes it easy to scale your bot.
5. Why are filters important in Pyrogram?
Filters help your bot process only the required updates. They improve performance and keep your handler functions clean and organized.
6. Is Pyrogram still maintained?
No. Pyrogram has been discontinued. Existing bots still work, but for new long term projects you should evaluate actively maintained alternatives.
7. Which Python version is recommended for Pyrogram?
Python 3.7 or higher is recommended. Using a modern Python version ensures better compatibility and performance.
8. Can Pyrogram handle both private and group messages?
Yes. With proper filters like filters.private and filters.group, your bot can easily handle messages from different chat types.
Also Read: