Telethon

https://docs.telethon.dev/en/v2/
Admin
Telethon is a Python library that makes it easy to interact with Telegram by providing a wrapper...
Tokens:71,554
Snippets:731
Trust Score:7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Installation Commands

Source: https://docs.telethon.dev/en/v2/basic/installation.html

Commands to check Python installation, install Telethon stable and development versions, and verify the installation.

```bash
python --version

```

```bash
python -m pip install --upgrade "telethon~=2.0"

```

```bash
python -m pip install --upgrade https://github.com/LonamiWebs/Telethon/archive/v2.zip#subdirectory=client

```

```bash
python -c "import telethon; print(telethon.__version__)"

```

--------------------------------

### Message and Button Examples

Source: https://docs.telethon.dev/en/v2/modules/types.html

Code examples demonstrating message iteration and button layout.

```python
async for message in client.iter_messages(chat):
    if not message:
        print('Found empty message with ID', message.id)
```

```python
buttons = [
    [col_0,        col_1],  # row 0
    [       col_0       ],  # row 1
    [col_0, col_1]  # the middle button on the bottom row
]
```

--------------------------------

### Client Method Examples

Source: https://docs.telethon.dev/en/v2/modules/client.html

Examples of using various client methods: read_message, request_login_code, resolve_peers, resolve_phone, resolve_username.

```python
# Mark all messages as read
await client.read_message(chat, 'all')
```

```python
login_token = await client.request_login_code('+1 23 456...')
print(login_token.timeout, 'seconds before code expires')
```

```python
[user, group, channel] = await client.resolve_peers([
    user_ref, group_ref, channel_ref
])
```

```python
print(await client.resolve_phone('+1 23 456'))
```

```python
print(await client.resolve_username('@cat'))
```

--------------------------------

### Verify Telethon installation

Source: https://docs.telethon.dev/en/v2/_sources/basic/installation.rst.txt

Confirm the library is installed correctly by printing the installed version number.

```shell
python -c "import telethon; print(telethon.__version__)"
```

--------------------------------

### Client class usage examples

Source: https://docs.telethon.dev/en/v2/modules/client.html

Examples of using the Client class methods: search_all_messages, search_messages, and send_audio.

```python
async for message in client.search_all_messages(query='hello'):
    print(message.text)
```

```python
async for message in client.search_messages(chat, query='hello'):
    print(message.text)
```

```python
await client.send_audio(chat, 'file.ogg', voice=True)
```

--------------------------------

### Basic Telethon Bot Setup

Source: https://docs.telethon.dev/en/v2/_sources/concepts/botapi-vs-mtproto.rst.txt

Demonstrates the basic setup for a Telethon bot, including client creation, interactive login, event handling for the /start command, and running until disconnected.

```python
async def start(event):
    await event.respond("I'm a bot, please talk to me!")

async def main():
    async with Client('bot', api_id, api_hash) as client:
        await client.interactive_login('TOKEN')
        client.add_event_handler(start, NewMessage, filters.Command('/start'))
        await client.run_until_disconnected()

asyncio.run(main())
```

--------------------------------

### send_file example

Source: https://docs.telethon.dev/en/v2/modules/client.html

Example of sending a file using the client.send_file method, including sending in-memory bytes.

```python
await client.send_file(chat, 'picture.jpg')

# Sending in-memory bytes
import io
data = b'my in-memory document'
cawait client.send_file(chat, io.BytesIO(data), size=len(data), name='doc.txt')
```

--------------------------------

### Send Draft Example

Source: https://docs.telethon.dev/en/v2/modules/types.html

Example of sending a draft message.

```python
await draft.send(clear=False)
```

--------------------------------

### Documentation

Source: https://docs.telethon.dev/en/v2/developing/contributing.html

Install the client package in editable mode for documentation generation.

```bash
pip install -e client/.

```

--------------------------------

### Aiogram v3 Example

Source: https://docs.telethon.dev/en/v2/concepts/botapi-vs-mtproto.html

The original aiogram v3 example with logging and comments removed, showing a command handler for /start and an echo handler.

```python
import asyncio

from aiogram import Bot, Dispatcher, types
from aiogram.enums import ParseMode
from aiogram.filters import CommandStart
from aiogram.types import Message
from aiogram.utils.markdown import hbold

dp = Dispatcher()

@dp.message(CommandStart())
async def command_start_handler(message: Message) -> None:
    await message.answer(f"Hello, {hbold(message.from_user.full_name)}!")

@dp.message()
async def echo_handler(message: types.Message) -> None:
    try:
        await message.send_copy(chat_id=message.chat.id)
    except TypeError:
        await message.answer("Nice try!")

async def main() -> None:
    bot = Bot(TOKEN, parse_mode=ParseMode.HTML)
    await dp.start_polling(bot)

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

--------------------------------

### PeerRef.from_str example

Source: https://docs.telethon.dev/en/v2/modules/types.html

Example demonstrating the round-trip conversion of a PeerRef to and from its string representation.

```python
ref: PeerRef = ...
assert PeerRef.from_str(str(ref)) == ref

```

--------------------------------

### Linting

Source: https://docs.telethon.dev/en/v2/developing/contributing.html

Install the client package with development dependencies and run the linting/checking script.

```bash
pip install -e client/[dev]
python tools/check.py

```

--------------------------------

### Install development version

Source: https://docs.telethon.dev/en/v2/_sources/basic/installation.rst.txt

Install the latest unreleased changes from the GitHub repository. Not recommended for production use.

```shell
python -m pip install --upgrade https://github.com/LonamiWebs/Telethon/archive/v2.zip#subdirectory=client
```

--------------------------------

### add_event_handler example

Source: https://docs.telethon.dev/en/v2/modules/client.html

Example of registering an event handler with the add_event_handler method.

```python
async def my_print_handler(event):
    print(event.chat.name, event.text)

# Register a handler to be called on new messages
client.add_event_handler(my_print_handler, events.NewMessage)

# Register a handler to be called on new messages if they contain "hello" or "/start"
from telethon.events import filters

client.add_event_handler(
    my_print_handler,
    events.NewMessage,
    filters.Any(filters.Text(r'hello'), filters.Command('/start')),
)
```

--------------------------------

### Raw API Usage Examples

Source: https://docs.telethon.dev/en/v2/concepts/full-api.html

Examples of invoking Raw API methods and checking response types.

```python
from telethon import _tl as tl

was_reset = await client(tl.functions.account.reset_wall_papers())
```

```python
invite = await client(tl.functions.messages.check_chat_invite(hash='aBcDeF'))
if isinstance(invite, tl.types.ChatInviteAlready):
    print(invite.chat)
```

--------------------------------

### Album preparation and sending

Source: https://docs.telethon.dev/en/v2/modules/types.html

Example of preparing an album, adding photos, and sending it to a chat.

```python
album = await client.prepare_album()
for photo in ('a.jpg', 'b.png'):
    await album.add_photo(photo)

messages = await album.send(chat)

```

--------------------------------

### connect example

Source: https://docs.telethon.dev/en/v2/modules/client.html

Connects to the Telegram servers. Returns None on success.

```python
await client.connect()
# success!
```

--------------------------------

### Type Language Definition Examples

Source: https://docs.telethon.dev/en/v2/_sources/developing/contributing.rst.txt

Examples of TL-definitions showing constructor identifiers, fields, and conditional serialization.

```text
geoPointEmpty#1117dd5f = GeoPoint;
geoPoint#b2a2f663 flags:# long:double lat:double access_hash:long accuracy_radius:flags.0?int = GeoPoint;
```

--------------------------------

### Client context manager

Source: https://docs.telethon.dev/en/v2/modules/client.html

Example of using the Client class as an asynchronous context manager.

```python
async with Client(session, api_id, api_hash) as client:
    ...  # automatically connect()-ed

...  # after exiting the block, disconnect() was automatically called
```

--------------------------------

### Error Handling Examples

Source: https://docs.telethon.dev/en/v2/modules/types.html

Examples demonstrating the usage of telethon.errors factory object and RpcError handling.

```python
from telethon import errors

try:
    await client.send_message(chat, text)
except errors.FloodWait as e:
    await asyncio.sleep(e.value)

```

```python
from telethon import RpcError

try:
    await client.send_message(chat, text)
except RpcError as e:
    if e.name == 'FLOOD_WAIT':
        await asyncio.sleep(e.value)
    else:
        raise

```

```python
try:
    await client.send_message(chat, text)
except errors.Code420:
    await asyncio.sleep(e.value)

```

```python
try:
    await client.send_message(chat, text)
except RpcError as e:
    if e.code == 420:
        await asyncio.sleep(e.value)
    else:
        raise

```

--------------------------------

### Generate Documentation

Source: https://docs.telethon.dev/en/v2/_sources/developing/contributing.rst.txt

Installs documentation dependencies and runs the docgen script to build project documentation.

```sh
pip install -e client/[doc]
python tools/docgen.py
```

--------------------------------

### AsyncList usage

Source: https://docs.telethon.dev/en/v2/modules/types.html

Example of awaiting an AsyncList returned by client.get_messages().

```python
# You can await it directly:
messages = await client.get_messages(chat, 1)
# ...and now messages is a normal list with a single are fetched lazily, rather than all up-front.
```

--------------------------------

### Install stable Telethon

Source: https://docs.telethon.dev/en/v2/_sources/basic/installation.rst.txt

Install or upgrade the latest stable version of the Telethon package using pip.

```shell
python -m pip install --upgrade "telethon~=2.0"
```

--------------------------------

### Telethon Client Example

Source: https://docs.telethon.dev/en/v2/index.html

A basic Telethon client example that logs in interactively, sends a message to the logged-in user, and replies to any incoming message containing 'hello' (case-insensitive).

```python
import asyncio
from telethon import Client, events
from telethon.events import filters

async def main():
    async with Client('name', api_id, api_hash) as client:
        me = await client.interactive_login()
        await client.send_message(me, f'Hello, {me.name}!')

        @client.on(events.NewMessage, filters.Text(r'(?i)hello'))
        async def handler(event):
            await event.reply('Hey!')

        await client.run_until_disconnected()

asyncio.run(main())
```

--------------------------------

### download example

Source: https://docs.telethon.dev/en/v2/modules/client.html

Downloads media files. The extension is not automatically added; use telethon.types.File.ext. Overwrites existing files.

```python
if photo := message.photo:
    await client.download(photo, f'picture{photo.ext}')

if video := message.video:
    with open(f'video{video.ext}', 'wb') as file:
        await client.download(video, file)
```

--------------------------------

### InlineButton type check example

Source: https://docs.telethon.dev/en/v2/modules/types.html

Example showing how to check if a button is inline or keyboard using the buttons module.

```python
from telethon.types import buttons

is_inline_button = isinstance(button, buttons.Inline)
is_keyboard_button = not isinstance(button, buttons.Inline)

```

--------------------------------

### Run the asyncio REPL

Source: https://docs.telethon.dev/en/v2/basic/signing-in.html

Start the built-in asyncio-enabled REPL to run the interactive login code interactively.

```bash
python -m asyncio

```

--------------------------------

### bot_sign_in example

Source: https://docs.telethon.dev/en/v2/modules/client.html

Signs in to a bot account using a bot token. Check is_authorized() before calling to avoid RPC errors.

```python
user = await client.bot_sign_in('12345:abc67DEF89ghi')
print('Signed in to bot account:', user.name)
```

--------------------------------

### Send a video

Source: https://docs.telethon.dev/en/v2/modules/client.html

Example of sending a video with markdown caption.

```python
await client.send_video(chat, 'video.mp4', caption_markdown='*I cannot believe this just happened*')
```

--------------------------------

### Run Linting and Checks

Source: https://docs.telethon.dev/en/v2/_sources/developing/contributing.rst.txt

Installs development dependencies and runs the check script for formatting, type-checking, and testing.

```sh
pip install -e client/[dev]
python tools/check.py
```

--------------------------------

### Automate Test Login Procedure in Python

Source: https://docs.telethon.dev/en/v2/_sources/concepts/datacenters.rst.txt

Example of automating the login process for a test account using a specific data center and generated credentials.

```python
from random import randrange
from telethon import Client
from telethon.session import DataCenter

datacenter = DataCenter(id=2, ipv4_addr='149.154.167.40:443')
phone = f'{randrange(1, 9999):04}'
login_code = str(datacenter.id) * 5
client = Client(..., datacenter=datacenter)

async with client:
    if not await client.is_authorized():
        login_token = await client.request_login_code(phone_or_token)
        await client.sign_in(login_token, login_code)
```

--------------------------------

### Send a photo

Source: https://docs.telethon.dev/en/v2/modules/client.html

Example of sending a photo with a caption.

```python
await client.send_photo(chat, 'photo.jpg', caption='Check this out!')
```

--------------------------------

### Send a message

Source: https://docs.telethon.dev/en/v2/modules/client.html

Example of sending a message with markdown formatting.

```python
await client.send_message(chat, markdown='**Hello!**')
```

--------------------------------

### Migrate PTB v20.x to Telethon

Source: https://docs.telethon.dev/en/v2/_sources/concepts/botapi-vs-mtproto.rst.txt

Comparison of a basic command handler setup between PTB v20.x and Telethon, highlighting the use of async/await and client lifecycle management.

```python
from telegram import Update
from telegram.ext import ApplicationBuilder, ContextTypes, CommandHandler

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await context.bot.send_message(chat_id=update.effective_chat.id, text="I'm a bot, please talk to me!")

if __name__ == '__main__':
    application = ApplicationBuilder().token('TOKEN').build()

    start_handler = CommandHandler('start', start)
    application.add_handler(start_handler)

    application.run_polling()
```

```python
import asyncio
from telethon import Client
from telethon.events import NewMessage, filters

async def start(update: NewMessage):
    await update.client.send_message(chat=update.chat, text="I'm a bot, please talk to me!")

async def main():
    application = Client('bot', api_id, api_hash)

    start_filter = filters.Command('/start')
    application.add_event_handler(start, NewMessage, start_filter)

    async with application:
        await application.interactive_login('TOKEN')
        await application.run_until_disconnected()

asyncio.run(main())
```

```python
import asyncio
from telethon import Client, events
from telethon.events import filters

@client.on(events.NewMessage, filters.Command('/start'))
```

--------------------------------

### Migrating from asynchronous TeleBot

Source: https://docs.telethon.dev/en/v2/concepts/botapi-vs-mtproto.html

Migration examples from asynchronous TeleBot to Telethon, showing the original TeleBot code and the Telethon equivalent.

```python
from telebot.async_telebot import AsyncTeleBot
bot = AsyncTeleBot('TOKEN')

# Handle '/start' and '/help'
@bot.message_handler(commands=['help', 'start'])
async def send_welcome(message):
    await bot.reply_to(message, """\
Hi there, I am EchoBot.
I am here to echo your kind words back to you. Just say anything nice and I'll say the exact same thing to you!\
""")

# Handle all other messages with content_type 'text' (content_types defaults to ['text'])
@bot.message_handler(func=lambda message: True)
async def echo_message(message):
    await bot.reply_to(message, message.text)

import asyncio
asyncio.run(bot.polling())

```

```python
from telethon import Client, events
from telethon.events.filters import Any, Command, Media
bot = Client('bot', api_id, api_hash)

# Handle '/start' and '/help'
@bot.on(events.NewMessage, Any(Command('/help'), Command('/start')))
async def send_welcome(message: NewMessage):
    await message.reply("""\
Hi there, I am EchoBot.
I am here to echo your kind words back to you. Just say anything nice and I'll say the exact same thing to you!\
""")

# Handle all other messages without media (negating the filter using ~)
@bot.on(events.NewMessage, ~Media())
async def echo_message(message: NewMessage):
    await message.reply(message.text)

import asyncio
async def main():
    async with bot:
        await bot.run_until_disconnected()

asyncio.run(main())

```

--------------------------------

### Run Code Generation

Source: https://docs.telethon.dev/en/v2/_sources/developing/contributing.rst.txt

Installs the generator package and executes the codegen script to update client implementation files.

```sh
pip install -e generator/
python tools/codegen.py
```

--------------------------------

### Set a draft with edit_draft

Source: https://docs.telethon.dev/en/v2/modules/client.html

Sets a draft in a chat. The first example sets a draft with no formatting and prints the date Telegram registered. The second example uses HTML formatting, a reply, and enables the link preview.

```python
# Set a draft with no formatting and print the date Telegram registered
draft = await client.edit_draft(chat, 'New text')
print('Set current draft on', draft.date)

# Set a draft using HTML formatting, with a reply, and enabling the link preview
await client.edit_draft(
    chat,
    html='Draft with <em>reply</em> an URL https://example.com',
    reply_to=message_id,
    link_preview=True
)
```

--------------------------------

### PeerRef round-trip

Source: https://docs.telethon.dev/en/v2/modules/types.html

Example of converting a PeerRef to string and back.

```python
ref: PeerRef = ...
assert PeerRef.from_str(str(ref)) == ref
```

--------------------------------

### Code generation

Source: https://docs.telethon.dev/en/v2/developing/contributing.html

Install the generator package in editable mode and run the code generation script.

```bash
pip install -e generator/
python tools/codegen.py

```

--------------------------------

### CommonMark formatting syntax

Source: https://docs.telethon.dev/en/v2/_sources/concepts/messages.rst.txt

Examples of supported Markdown-like syntax for message formatting.

```text
*italic* and _italic_
**bold** and __bold__
# headings are underlined
~~strikethrough~~
[inline URL](https://www.example.com/)
[inline mention](tg://user?id=ab1234cd6789)
custom emoji image with ![👍](tg://emoji?id=1234567890)
`inline code`
```python
multiline pre-formatted
block with optional language
```
```

--------------------------------

### Configure Custom Proxy Connector in Python

Source: https://docs.telethon.dev/en/v2/_sources/concepts/datacenters.rst.txt

Example of implementing a custom connector to route traffic through a SOCKS5 proxy using python-socks.

```python
import asyncio
from functools import partial
from python_socks.async_.asyncio import Proxy
from telethon import Client

async def my_proxy_connector(ip, port, *, proxy_url):
    # Refer to python-socks for an up-to-date way to define and use proxies.
    # This is just an example of a custom connector.
    proxy = Proxy.from_url(proxy_url)
    sock = await proxy.connect(dest_host='example.com', dest_port=443)
    return await asyncio.open_connection(
        host=ip,
        port=port,
        sock=sock,
        ssl=ssl.create_default_context(),
        server_hostname='example.com',
    )

client = Client(..., connector=partial(
    my_proxy_connector,
    proxy_url='socks5://user:password@127.0.0.1:1080'
))
```

--------------------------------

### check_password example

Source: https://docs.telethon.dev/en/v2/modules/client.html

Completes 2FA login by checking the password token. Requires request_login_code() and sign_in() first.

```python
from telethon.types import PasswordToken

login_token = await client.request_login_code('+1 23 456')
password_token = await client.sign_in(login_token, input('code: '))
assert isinstance(password_token, PasswordToken)

user = await client.check_password(password_token, '1-L0V3+T3l3th0n')
print('Signed in to 2FA-protected account:', user.name)
```

--------------------------------

### Not Filter Usage

Source: https://docs.telethon.dev/en/v2/modules/events.html

Example demonstrating the use of the Not filter and its equivalent with the ~ operator.

```python
from telethon.events.filters import All, Command

@bot.on(events.NewMessage, Not(Command('/start'))
async def handler(event): ...

# equivalent to:

@bot.on(events.NewMessage, ~Command('/start'))
async def handler(event): ...

```

--------------------------------

### Check Python version

Source: https://docs.telethon.dev/en/v2/_sources/basic/installation.rst.txt

Verify that Python is installed and accessible in your terminal environment.

```shell
python --version
```

--------------------------------

### Avoiding event loop issues with asyncio.run()

Source: https://docs.telethon.dev/en/v2/developing/faq.html

Example showing how to avoid event loop issues by using a single async main function and asyncio.run().

```python
# It's fine to create the client outside as long as you don't connect
client = Client(...)

async def main():
    # Now the client will connect, so the loop must not change from now on.
    # But as long as you do all the work inside main, including calling
    # other async functions, things will work.
    async with client:
        ....

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

```

--------------------------------

### disconnect example

Source: https://docs.telethon.dev/en/v2/modules/client.html

Disconnects from the Telegram servers. Only fails if saving the session fails.

```python
await client.disconnect()
# success!
```

--------------------------------

### Migrate PTB v13.x to Telethon

Source: https://docs.telethon.dev/en/v2/_sources/concepts/botapi-vs-mtproto.rst.txt

Comparison of a basic command handler setup between PTB v13.x and Telethon, including an idiomatic Telethon approach using decorators.

```python
from telegram import Update
from telegram.ext import Updater, CallbackContext, CommandHandler

updater = Updater(token='TOKEN', use_context=True)
dispatcher = updater.dispatcher

def start(update: Update, context: CallbackContext):
    context.bot.send_message(chat_id=update.effective_chat.id, text="I'm a bot, please talk to me!")

start_handler = CommandHandler('start', start)
dispatcher.add_handler(start_handler)

updater.start_polling()
```

```python
import asyncio
from telethon import Client
from telethon.events import NewMessage, filters

updater = Client('bot', api_id, api_hash)

async def start(update: NewMessage):
    await update.client.send_message(chat=update.chat.id, text="I'm a bot, please talk to me!")

start_filter = filters.Command('/start')
updater.add_event_handler(start, NewMessage, start_filter)

async def main():
    async with updater:
        await updater.interactive_login('TOKEN')
        await updater.run_until_disconnected()

asyncio.run(main())
```

```python
import asyncio
from telethon import Client, events
from telethon.events import filters

client = Client('bot', api_id, api_hash)

@client.on(events.NewMessage, filters.Command('/start'))
async def start(event):
    await event.respond("I'm a bot, please talk to me!")

async def main():
    async with client:
        await client.interactive_login('TOKEN')
        await client.run_until_disconnected()

asyncio.run(main())
```

--------------------------------

### Basic asyncio sleep example

Source: https://docs.telethon.dev/en/v2/developing/faq.html

A simple asyncio program that sleeps for a day, used to demonstrate the default KeyboardInterrupt behavior.

```python
import asyncio

asyncio.run(asyncio.sleep(86400))

```

--------------------------------

### Awaiting asynchronous calls

Source: https://docs.telethon.dev/en/v2/developing/faq.html

Example showing the correct use of await with an asynchronous Telethon call.

```python
async def handler(event):
    me = await client.get_me()
    #    ^^^^^ note the await
    print(me.id)

```

--------------------------------

### Set chat default restrictions

Source: https://docs.telethon.dev/en/v2/modules/client.html

Example of setting and removing default chat restrictions.

```python
from datetime import datetime, timedelta
from telethon.types import ChatRestriction

# Don't allow anyone except administrators to send stickers for a day
await client.set_chat_default_restrictions(
    chat, user, [ChatRestriction.SEND_STICKERS],
    until=datetime.now() + timedelta(days=1))

# Remove all default restrictions from the chat
await client.set_chat_default_restrictions(chat, user, [])
```

--------------------------------

### Example bot token

Source: https://docs.telethon.dev/en/v2/basic/signing-in.html

Shows the format of a bot token obtained from @BotFather. The entire string is the token, not API ID and hash separated by a colon.

```text
54321:hJrIQtVBab0M2Yqg4HL1K-EubfY_v2fEVR

```
Tokens:
Raw