Pyrogram

Warnings

• breaking Project is no longer maintained or supported. Users should be aware that new features, bug fixes, or security updates are unlikely.
  Fix: Consider migrating to actively maintained alternatives or be prepared to fork and maintain the library yourself. Proceed with caution for new projects.
• breaking Authorization flow changed: Callback functions for `Client` arguments (e.g., `phone_number`, `password`) were removed in favor of a simpler, sequential authorization.
  Fix: Update authorization logic to use the direct parameters or environmental variables for `api_id`, `api_hash`, `phone_number`, `password`, etc., and follow the interactive login flow if necessary.
• breaking The `idle()` method no longer automatically stops the client. It only idles.
  Fix: Explicitly call `app.stop()` after `idle()` finishes if you want to terminate the client gracefully.
• gotcha Session persistence is managed via session files (SQLite by default). For ephemeral environments or explicit in-memory use, `in_memory=True` must be passed to `Client`.
  Fix: Understand the `name` and `in_memory` parameters of `Client` to control session storage. Use `export_session_string()` for portable in-memory sessions across restarts.
• gotcha All Pyrogram operations are asynchronous. Blocking operations (e.g., `time.sleep()`, synchronous network requests) in handlers will freeze the event loop and prevent other updates from being processed.
  Fix: Always use `await` with Pyrogram methods and other asynchronous libraries (e.g., `asyncio.sleep()`, `aiohttp`). Ensure your code is fully asynchronous.

Install

• pip install pyrogram Basic Installation
• pip install pyrogram[tgcrypto] With C-based cryptography for performance

Imports

• Client

  from pyrogram import Client

• filters

  from pyrogram import filters

• RPCError
  wrong:

  from pyrogram import Error

  correct:

  from pyrogram import errors; errors.RPCError

  The `errors` package was moved and `Error` renamed to `RPCError` in v0.12.0.
• idle
  wrong:

  Client.idle()

  correct:

  from pyrogram import idle

  The `idle()` method was reworked to be a static function, not a client method, and no longer stops the client automatically.

Quickstart

This quickstart initializes a Pyrogram client (which can act as a user account or bot). It requires `api_id` and `api_hash` from my.telegram.org/apps set as environment variables `TG_API_ID` and `TG_API_HASH`. For bots, `TG_BOT_TOKEN` should also be set. The client will create a `.session` file for persistent login. It includes a simple `start` command handler.

import os
from pyrogram import Client, filters
import asyncio

API_ID = os.environ.get('TG_API_ID', '')
API_HASH = os.environ.get('TG_API_HASH', '')
BOT_TOKEN = os.environ.get('TG_BOT_TOKEN', '') # Optional, for bot accounts

async def main():
    if not API_ID or not API_HASH:
        print("Please set TG_API_ID and TG_API_HASH environment variables.")
        return

    # For a user account, use Client("my_account", api_id, api_hash)
    # For a bot account, use Client("my_bot", api_id, api_hash, bot_token)
    async with Client(
        "my_session", # Session name, creates my_session.session file
        api_id=int(API_ID),
        api_hash=API_HASH,
        bot_token=BOT_TOKEN if BOT_TOKEN else None # Pass bot_token only for bots
    ) as app:
        me = await app.get_me()
        print(f"Client started as {me.first_name} (@{me.username})")

        @app.on_message(filters.command("start") & filters.private)
        async def start_command(client, message):
            await message.reply_text("Hello! I'm a Pyrogram client/bot.")

        # Keep the client running indefinitely. In a real app, you might use app.run()
        # or integrate with other async loops.
        print("Listening for messages...")
        await asyncio.Event().wait() # Keeps the client running indefinitely

if __name__ == "__main__":
    asyncio.run(main())