python-telegram

To use the library, you must first register an application at my.telegram.org to obtain an api_id and api_hash.

Key Concepts:

• Authentication: Sign in using a phone number or a bot_token (to act as a bot).
• Database: You must provide a database_encryption_key and a files_directory.
• Chat Availability: A chat must exist in the tdlib database before you can interact with it (e.g., sending messages). Use get_chats(limit=...) to load chats into the local database.
• Asynchronicity: All library calls return an AsyncResult object. You must call the .wait() method on this object to retrieve the actual result.
• Lifecycle: Always call tg.stop() at the end of your script to clean up.

from telegram.client import Telegram
from telegram.text import Spoiler

tg = Telegram(
    api_id=123456,
    api_hash="api_hash",
    phone="+31611111111",  # or use 'bot_token'
    database_encryption_key="changekey123",
    files_directory="/tmp/.tdlib_files/",
)
tg.login()

# Load chats into the database first
result = tg.get_chats(limit=100)
result.wait()

# Send a message
chat_id = 123456789
result = tg.send_message(chat_id, Spoiler("Hello world!"))
result.wait()
print(result.update)

tg.stop()

By default, python-telegram uses a blocking login method that prompts for credentials in the terminal. For environments without a terminal (like web applications), use login(blocking=False).

This method returns the current AuthorizationState instead of prompting. You must inspect the returned state, provide the required credentials using the appropriate method, and then call login(blocking=False) again to continue the process. The process is complete when login returns AuthorizationState.READY or when tg.authorization_state equals AuthorizationState.READY.

from telegram.client import Telegram, AuthorizationState

tg = Telegram(
    api_id=123456,
    api_hash='api_hash',
    phone='+31611111111',
    database_encryption_key='changeme1234',
)

# Start non-blocking login
state = tg.login(blocking=False)

if state == AuthorizationState.WAIT_CODE:
    tg.send_code('some-code')
    state = tg.login(blocking=False)  # Continue process

if state == AuthorizationState.WAIT_PASSWORD:
    tg.send_password('secret-password')
    state = tg.login(blocking=False)  # Continue process

# When state is AuthorizationState.READY, you are logged in.

The login() method initiates the authentication process. It is a prerequisite for all other API calls.

Depending on the blocking argument, login() behaves differently:

• blocking=True (default): The method will attempt to handle the entire login flow, including prompting for codes/passwords via standard input (stdin).
• blocking=False: The method returns the current AuthorizationState. You must then call specific methods (like send_code, send_password, etc.) to progress the state and call login(blocking=False) again until the state reaches AuthorizationState.READY.

Common AuthorizationState values returned:

• WAIT_CODE: Requires a Telegram code.
• WAIT_PASSWORD: Requires a 2FA password.
• WAIT_EMAIL_CODE: Requires an email verification code.
• READY: Authentication successful.

# Blocking login (easiest for CLI scripts)
state = client.login(blocking=True)
if state == AuthorizationState.READY:
    print("Logged in!")

# Non-blocking login (for integration into GUIs or web apps)
state = client.login(blocking=False)
if state == AuthorizationState.WAIT_CODE:
    # ... get code from user ...
    client.send_code(user_provided_code)
    # then call login again
    client.login(blocking=False)

To create a bot, register a message handler using add_message_handler(callback). The callback function receives an update dictionary.

To process text messages, navigate the update dictionary structure: update['message']['content'].get('text', {}).

Use tg.send_message(chat_id=..., text=...) to reply to users.

from telegram.client import Telegram

tg = Telegram(
    api_id=123456,
    api_hash='api_hash',
    phone='+31611111111',
    database_encryption_key='changeme1234',
)
tg.login()

def new_message_handler(update):
    # Extract text content safely
    message_content = update['message']['content'].get('text', {})
    message_text = message_content.get('text', '').lower()
    is_outgoing = update['message']['is_outgoing']

    # Logic: if incoming message is 'ping', reply 'pong'
    if not is_outgoing and message_text == 'ping':
        chat_id = update['message']['chat_id']
        print(f'Ping has been received from {chat_id}')
        tg.send_message(
            chat_id=chat_id,
            text='pong',
        )

tg.add_message_handler(new_message_handler)
tg.idle()