aiotdlib

The Client class is the main entry point. You can configure it using ClientSettings. You can also provide configuration via environment variables with the prefix AIOTDLIB_* (e.g., AIOTDLIB_API_ID, AIOTDLIB_API_HASH, AIOTDLIB_BOT_TOKEN).

All TDLib functions are accessible through the client.api field.

import asyncio
from aiotdlib import Client, ClientSettings

API_ID = 123456
API_HASH = ""
PHONE_NUMBER = ""

async def main():
    client = Client(
        settings=ClientSettings(
            api_id=API_ID,
            api_hash=API_HASH,
            phone_number=PHONE_NUMBER
        )
    )

    async with client:
        # Access TDLib functions via client.api
        me = await client.api.get_me()
        print(f"Logged in as: {me.model_dump_json()}")

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

You can install aiotdlib using pip or poetry.

Requirements:

• Python 3.9+
• Telegram api_id and api_hash (obtainable from Telegram docs).

Note: This package includes prebuilt TDLib binaries for macOS (arm64) and Debian (amd64). To use a custom binary, pass the library_path argument to the Client constructor.

# Using pip
pip install aiotdlib

# Using poetry
poetry add aiotdlib

You can route your Telegram connection through a proxy by configuring proxy_settings within ClientSettings. Supported types include ClientProxyType.SOCKS5.

from aiotdlib import Client, ClientSettings, ClientProxySettings, ClientProxyType

async def main():
    client = Client(
        settings=ClientSettings(
            api_id=123456,
            api_hash="",
            phone_number="",
            proxy_settings=ClientProxySettings(
                host="10.0.0.1",
                port=3333,
                type=ClientProxyType.SOCKS5,
                username="aiotdlib",
                password="somepassword",
            )
        )
    )
    async with client:
        await client.idle()

The Client class is the primary entry point for interacting with Telegram via TDLib. It can be used as an asynchronous context manager to ensure proper startup and shutdown.

To start the client, use await client.start(). This handles TDLib parameter setup, proxy configuration, and the authorization process (phone number, bot token, etc.). To stop the client and clean up resources, use await client.stop() or exit the async with block.

from aiotdlib.client import Client
from aiotdlib.client_settings import ClientSettings

async def main():
    settings = ClientSettings(api_id=123, api_hash='hash', bot_token='token')
    async with Client(settings=settings) as client:
        # Your code here
        pass

import asyncio
asyncio.run(main())

Since ClientSettings inherits from pydantic_settings.BaseSettings, you can configure it using environment variables. All variables must be prefixed with aiotdlib_.

Example Environment Variables:

• AIOTDLIB_API_ID
• AIOTDLIB_API_HASH
• AIOTDLIB_PHONE_NUMBER
• AIOTDLIB_BOT_TOKEN

Settings can also be loaded from a .env file.

The Client provides convenience methods for common message types using predefined filters:

• text_message_handler(function): Registers a handler for UPDATE_NEW_MESSAGE events that specifically contain text content.
• bot_command_handler(function, command=None): Registers a handler for UPDATE_NEW_MESSAGE events where the text starts with / (and optionally matches a specific command).

# As a decorator
@client.text_message_handler
async def on_text(client, update):
    print(update.message.content.text)

# As a command handler
@client.bot_command_handler(command="start")
async def on_start(client, update):
    print("User sent /start")

Sends an animation (e.g., GIF) to a target chat. The animation parameter can be a local file path or a remote file_id.

await client.send_animation(
    chat_id=123456,
    animation="/path/to/animation.gif",
    caption="Cool animation"
)

For low-level interaction with TDLib:

• request(query, request_id=None, request_timeout=10): Sends a query and waits for the specific response associated with that request_id. It returns the BaseObject result of the request.
• execute(query): Executes a query without waiting for a specific response object, returning the raw result of the execution. It raises AioTDLibError if the execution fails.

from aiotdlib.api import GetCurrentState

# Using request to get a specific object
state = await client.request(GetCurrentState())

# Using execute for raw commands
await client.execute(SetLogVerbosityLevel(new_verbosity_level=1))