Telethon - Telegram Client Library

Warnings

• breaking Telethon v2.x is a complete rewrite and introduces significant breaking changes from v1.x (including API changes, renamed classes like TelegramClient to Client, and removal of telethon.sync). Code written for v1.x will likely not run on v2.x without substantial modification. Always consult the migration guide when upgrading to v2.x.
  Fix: Review the official 'Migrating from v1 to v2' documentation for detailed instructions on adapting your codebase to the new API and structure.
• gotcha Telethon is an asynchronous library. Incorrectly mixing asynchronous operations (like network requests) with synchronous code without proper `await` calls or an active `asyncio` event loop is a common mistake that can lead to unresponsive handlers, runtime errors, or unexpected behavior.
  Fix: Ensure all Telethon API calls within an `async` function are `await`ed. If integrating with synchronous code, use `asyncio.run()` for your main async function and avoid blocking the event loop.
• gotcha The `api_id` and `api_hash` are critical for client creation and must be obtained from your Telegram API development tools page (my.telegram.org). Using incorrect, placeholder, or expired values will prevent the client from connecting to Telegram.
  Fix: Always retrieve your unique `api_id` and `api_hash` from https://my.telegram.org. Store them securely, preferably in environment variables, and never hardcode them directly into public repositories.
• gotcha Session files (`.session`) contain your encrypted authentication keys and sensitive login information. They are essential for persistent logins and should be protected, excluded from version control (e.g., via `.gitignore`), and never shared. Using the same session file for multiple concurrently running Telethon clients will result in `sqlite3.OperationalError: database is locked` or similar connection issues.
  Fix: Treat session files as highly sensitive. Use a unique session name for each client instance, especially if running multiple scripts. If an error occurs, ensure no other process is holding the session file lock.
• gotcha Telegram API has rate limits. Sending too many requests in a short period can trigger `FloodWaitError`, requiring the client to wait for a specified duration before making further requests. While Telethon can automatically handle some `FloodWaitError` conditions, excessive flooding can lead to account bans.
  Fix: Implement proper delays and back-off strategies in your code, especially when performing bulk operations. Use the `FloodWaitError.seconds` attribute to dynamically adjust wait times. Monitor Telegram's official API guidelines for rate limits.
• gotcha For optimal performance, particularly concerning file downloads/uploads and update handling, it is highly recommended to install the `cryptg` package. Without it, Telethon defaults to a slower pure Python implementation for encryption/decryption, leading to reduced speed.
  Fix: Install `cryptg` using `pip install cryptg`. Verify its usage by enabling logging at INFO level before importing Telethon.

Install

• pip install telethon Install stable version

Imports

• TelegramClient

  from telethon import TelegramClient

• events

  from telethon import events

• errors

  from telethon import errors

• sync

  import telethon.sync

  While 'import telethon.sync' was a common pattern in v1.x to run async code synchronously, it is removed in v2.x and generally discouraged in favor of proper asyncio usage.

Quickstart

This quickstart demonstrates how to initialize and connect a Telethon client. It logs in the user (or registers if it's the first run) using the `api_id` and `api_hash` provided via environment variables. The session is saved to a `.session` file for persistence. The client runs asynchronously until manually disconnected.

import os
import asyncio
from telethon import TelegramClient

# Get API ID and API Hash from environment variables for security
# You can obtain these from https://my.telegram.org
api_id = int(os.environ.get('TG_API_ID', 0))
api_hash = os.environ.get('TG_API_HASH', '')

# 'session_name' will create 'session_name.session' file
# This file stores your login information and should be kept private.
client = TelegramClient('session_name', api_id, api_hash)

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

    print("Connecting to Telegram...")
    await client.start()
    print("Client Connected!")

    # Get information about yourself
    me = await client.get_me()
    print(f"Logged in as: {me.first_name} (@{me.username})")

    # Example: Send a message to yourself
    # await client.send_message('me', 'Hello from Telethon!')
    # print("Message sent to self!")

    # Keep the client running until disconnected (e.g., by Ctrl+C)
    await client.run_until_disconnected()

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