Telethon

https://docs.telethon.dev/en/stable/
Admin
Telethon is a Python library designed to simplify writing programs that interact with Telegram,...
Tokens:261,369
Snippets:2,438
Trust Score:7
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Configure Telethon client with MTProto proxy (uncommented)

Source: https://docs.telethon.dev/en/stable/_sources/basic/signing-in.rst.txt

The same MTProto proxy configuration as the commented example, but without comments for clarity. Use this when you need a concise version of the setup.

```python
from telethon import TelegramClient, connection

client = TelegramClient(
    'anon', api_id, api_hash,
    connection=connection.ConnectionTcpMTProxyRandomizedIntermediate,
    proxy=('mtproxy.example.com', 2002, 'secret')
)
```

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

### start

Source: https://docs.telethon.dev/en/stable/quick-references/client-reference.html

Starts the client (connects and logs in if necessary).

```APIDOC
## start

### Description
Starts the client (connects and logs in if necessary).

### Method
start

### Parameters
None documented.

### Returns
None documented.
```

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

### Basic asyncio example: run a coroutine with asyncio.run

Source: https://docs.telethon.dev/en/stable/_sources/concepts/asyncio.rst.txt

Shows the minimal setup to run an async function using asyncio.run(). Requires Python 3.7 or greater. The loop is created and torn down automatically.

```python
import asyncio

async def main():
    for char in 'Hello, world!\n':
        print(char, end='', flush=True)
        await asyncio.sleep(0.2)

asyncio.run(main())
```

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

### TelegramClient start and context manager usage

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

Shows how to create a TelegramClient and start it as a bot or user account, including handling the code and password prompts. Also demonstrates using the client as a context manager, which calls start() automatically.

```python
client = TelegramClient('anon', api_id, api_hash)

# Starting as a bot account
await client.start(bot_token=bot_token)

# Starting as a user account
await client.start(phone)
# Please enter the code you received: 12345
# Please enter your password: *******
# (You are now logged in)

# Starting using a context manager (this calls start()):
with client:
    pass
```

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

### get_messages example

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

Shows how to get messages with a filter, get all photos, and get a message by ID.

```python
# Get 0 photos and print the total to show how many photos there are
from telethon.tl.types import InputMessagesFilterPhotos
photos = await client.get_messages(chat, 0, filter=InputMessagesFilterPhotos)
print(photos.total)

# Get all the photos
photos = await client.get_messages(chat, None, filter=InputMessagesFilterPhotos)

# Get messages by ID:
message_1337 = await client.get_messages(chat, ids=1337)
```

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

### Example entity string output

Source: https://docs.telethon.dev/en/stable/concepts/strings.html

Example output of printing an entity. Shows the string representation with all attributes and their values.

```text
Channel(id=1066197625, title='Telegram Usernames', photo=ChatPhotoEmpty(), date=datetime.datetime(2016, 12, 16, 15, 15, 43, tzinfo=datetime.timezone.utc), version=0, creator=False, left=True, broadcast=True, verified=True, megagroup=False, restricted=False, signatures=False, min=False, scam=False, has_link=False, has_geo=False, slowmode_enabled=False, access_hash=-6309373984955162244, username='username', restriction_reason=[], admin_rights=None, banned_rights=None, default_banned_rights=None, participants_count=None)

```

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

### Example stringify output

Source: https://docs.telethon.dev/en/stable/concepts/strings.html

Example output of entity.stringify(). Shows a formatted, multi-line representation with each attribute on its own line.

```text
Channel(
    id=1066197625,
    title='Telegram Usernames',
    photo=ChatPhotoEmpty(
    ),
    date=datetime.datetime(2016, 12, 16, 15, 15, 43, tzinfo=datetime.timezone.utc),
    version=0,
    creator=False,
    left=True,
    broadcast=True,
    verified=True,
    megagroup=False,
    restricted=False,
    signatures=False,
    min=False,
    scam=False,
    has_link=False,
    has_geo=False,
    slowmode_enabled=False,
    access_hash=-6309373984955162244,
    username='username',
    restriction_reason=[
    ],
    admin_rights=None,
    banned_rights=None,
    default_banned_rights=None,
    participants_count=None
)

```

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

### Telethon basic client example

Source: https://docs.telethon.dev/en/stable/_sources/index.rst.txt

Basic usage example showing how to create a TelegramClient, send a message, download a profile photo, and handle incoming messages with an event handler. Requires api_id and api_hash from Telegram.

```python
from telethon.sync import TelegramClient, events

with TelegramClient('name', api_id, api_hash) as client:
   client.send_message('me', 'Hello, myself!')
   print(client.download_profile_photo('me'))

   @client.on(events.NewMessage(pattern='(?i).*Hello'))
   async def handler(event):
      await event.reply('Hey!')

   client.run_until_disconnected()
```

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

### InlineBuilder.document example

Source: https://docs.telethon.dev/en/stable/modules/custom.html

Creates an inline document result using the InlineBuilder.document method. The example shows sending a file when the user selects the result.

```python
results = [
    # Sending just the file when the user selects it.
    builder.document('/path/to/file.pdf'),

```

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

### InlineBuilder.article example

Source: https://docs.telethon.dev/en/stable/modules/custom.html

Creates a list of inline article results using the InlineBuilder.article method. Each article can send a text message, open a URL, or include buttons. The example shows three options with different behaviors.

```python
results = [
    # Option with title and description sending a message.
    builder.article(
        title='First option',
        description='This is the first option',
        text='Text sent after clicking this option',
    ),
    # Option with title URL to be opened when clicked.
    builder.article(
        title='Second option',
        url='https://example.com',
        text='Text sent if the user clicks the option and not the URL',
    ),
    # Sending a message with buttons.
    # You can use a list or a list of lists to include more buttons.
    builder.article(
        title='Third option',
        text='Text sent with buttons below',
        buttons=Button.url('https://example.com'),
    ),
]

```

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

### Conversation example with bot

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

Example usage of bot.conversation to send messages and get responses, including a loop to validate the name.

```python
# <you> denotes outgoing messages you sent
# <usr> denotes incoming response messages
with bot.conversation(chat) as conv:
    # <you> Hi!
    conv.send_message('Hi!')

    # <usr> Hello!
    hello = conv.get_response()

    # <you> Please tell me your name
    conv.send_message('Please tell me your name')

    # <usr> ?
    name = conv.get_response().raw_text

    while not any(x.isalpha() for x in name):
        # <you> Your name didn't have any letters! Try again
        conv.send_message("Your name didn't have any letters! Try again")

        # <usr> Human
        name = conv.get_response().raw_text

    # <you> Thanks Human!
    conv.send_message('Thanks {}!'.format(name))
```

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

### get_drafts: Retrieve drafts

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

Shows how to get drafts and access their text. The example prints the first draft's text and retrieves the draft in the 'me' chat.

```python
# Get drafts, print the text of the first
drafts = await client.get_drafts()
print(drafts[0].text)

# Get the draft in your chat
draft = await client.get_drafts('me')
print(drafts.text)
```

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

### Chain .start() with a bot token in a with block

Source: https://docs.telethon.dev/en/stable/misc/changelog.html

Shows chaining the `.start()` method because it returns the client instance, allowing you to use the client in a `with` block. Requires importing `sync` to use the synchronous methods.

```python
with TelegramClient(name, api_id, api_hash).start(bot_token=token) as bot:
    bot.send_message(chat, 'Hello!')

```

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

### Telethon quick-start: friendly methods for messages, files, and dialogs

Source: https://docs.telethon.dev/en/stable/_sources/basic/quick-start.rst.txt

Complete Telethon quick-start example showing friendly methods: get_me, iter_dialogs, send_message, send_file, iter_messages, and download_media. Requires your own api_id and api_hash from my.telegram.org. Telethon is asynchronous, so the main logic is inside an async def and run with client.loop.run_until_complete(main()).

```python
from telethon import TelegramClient

# Remember to use your own values from my.telegram.org!
api_id = 12345
api_hash = '0123456789abcdef0123456789abcdef'
client = TelegramClient('anon', api_id, api_hash)

async def main():
    # Getting information about yourself
    me = await client.get_me()

    # "me" is a user object. You can pretty-print
    # any Telegram object with the "stringify" method:
    print(me.stringify())

    # When you print something, you see a representation of it.
    # You can access all attributes of Telegram objects with
    # the dot operator. For example, to get the username:
    username = me.username
    print(username)
    print(me.phone)

    # You can print all the dialogs/conversations that you are part of:
    async for dialog in client.iter_dialogs():
        print(dialog.name, 'has ID', dialog.id)

    # You can send messages to yourself...
    await client.send_message('me', 'Hello, myself!')
    # ...to some chat ID
    await client.send_message(-100123456, 'Hello, group!')
    # ...to your contacts
    await client.send_message('+34600123123', 'Hello, friend!')
    # ...or even to any username
    await client.send_message('username', 'Testing Telethon!')

    # You can, of course, use markdown in your messages:
    message = await client.send_message(
        'me',
        'This message has **bold**, `code`, __italics__ and '
        'a [nice website](https://example.com)!',
        link_preview=False
    )

    # Sending a message returns the sent message object, which you can use
    print(message.raw_text)

    # You can reply to messages directly if you have a message object
    await message.reply('Cool!')

    # Or send files, songs, documents, albums...
    await client.send_file('me', '/home/me/Pictures/holidays.jpg')

    # You can print the message history of any chat:
    async for message in client.iter_messages('me'):
        print(message.id, message.text)

        # You can download media from messages, too!
        # The method will return the path where the file was saved.
        if message.photo:
            path = await message.download_media()
            print('File saved to', path)  # printed after download is done

with client:
    client.loop.run_until_complete(main())
```

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

### Filter entities by type with get_entities_text(MessageEntityCode)

Source: https://docs.telethon.dev/en/stable/modules/custom.html

Shows how to pass a specific entity type to get_entities_text to only get matching entities. The example prints the inner text for all code entities.

```python
>>> from telethon.tl.types import MessageEntityCode
>>>
>>> m = ...  # get the message
>>> for _, inner_text in m.get_entities_text(MessageEntityCode):
>>>     print(inner_text)
```

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

### Get input entity with client.get_input_entity()

Source: https://docs.telethon.dev/en/stable/_sources/concepts/full-api.rst.txt

Use client.get_input_entity() to obtain an InputPeer from a username or ID. The await must be inside an async def, and the example assumes you already know this pattern.

```python
import telethon

async def main():
    peer = await client.get_input_entity('someone')

client.loop.run_until_complete(main())
```

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

### send_file usage examples for various media types

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

Shows how to use client.send_file for photos, voice notes, round videos, custom thumbnails, force documents, albums, progress callbacks, dices, and contacts. Includes importing types from telethon.tl.

```python
# Normal files like photos
await client.send_file(chat, '/my/photos/me.jpg', caption="It's me!")
# or
await client.send_message(chat, "It's me!", file='/my/photos/me.jpg')

# Voice notes or round videos
await client.send_file(chat, '/my/songs/song.mp3', voice_note=True)
await client.send_file(chat, '/my/videos/video.mp4', video_note=True)

# Custom thumbnails
await client.send_file(chat, '/my/documents/doc.txt', thumb='photo.jpg')

# Only documents
await client.send_file(chat, '/my/photos/photo.png', force_document=True)

# Albums
await client.send_file(chat, [
    '/my/photos/holiday1.jpg',
    '/my/photos/holiday2.jpg',
    '/my/drawings/portrait.png'
])

# Printing upload progress
def callback(current, total):
    print('Uploaded', current, 'out of', total,
          'bytes: {:.2%}'.format(current / total))

await client.send_file(chat, file, progress_callback=callback)

# Dices, including dart and other future emoji
from telethon.tl import types
await client.send_file(chat, types.InputMediaDice(''))
await client.send_file(chat, types.InputMediaDice('🎯'))

# Contacts
await client.send_file(chat, types.InputMediaContact(
    phone_number='+34 123 456 789',
    first_name='Example',
    last_name='',
    vcard=''
))
```

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

### Automate replies with NewMessage event

Source: https://docs.telethon.dev/en/stable/_sources/basic/updates.rst.txt

A complete example that registers an event handler for NewMessage events. When a message contains 'hello', it replies with 'hi!'. The client is started and run until disconnected.

```python
from telethon import TelegramClient, events

client = TelegramClient('anon', api_id, api_hash)

@client.on(events.NewMessage)
async def my_event_handler(event):
    if 'hello' in event.raw_text:
        await event.reply('hi!')

client.start()
client.run_until_disconnected()
```

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

### Basic asyncio coroutine with asyncio.run()

Source: https://docs.telethon.dev/en/stable/concepts/asyncio.html

Shows how to import asyncio, define an async main() coroutine that prints characters with a delay, and run it using asyncio.run(). Requires Python 3.7 or greater.

```python
# First we need the asyncio library
import asyncio

# We also need something to run
async def main():
    for char in 'Hello, world!\n':
        print(char, end='', flush=True)
        await asyncio.sleep(0.2)

# Then, we can create a new asyncio loop and use it to run our coroutine.
# The creation and tear-down of the loop is hidden away from us.
asyncio.run(main())

```

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

### Get peer ID from username with client.get_peer_id

Source: https://docs.telethon.dev/en/stable/_sources/concepts/chats-vs-channels.rst.txt

Uses client.get_peer_id to convert a username or other entity that may require an API call into its numeric ID. The example prints the ID of 'me' (the current user).

```python
print(await client.get_peer_id('me'))  # your id
```

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

### send_message example with parse modes, buttons, and scheduling

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

Shows how to send messages with different parse modes (markdown, HTML, explicit), inline buttons, reply keyboards, force reply, clear buttons, and scheduled sending. Requires a logged-in client; bot accounts can send buttons. Note that code and pre tags break the documentation.

```python
# Markdown is the default
await client.send_message('me', 'Hello **world**!')

# Default to another parse mode
client.parse_mode = 'html'

await client.send_message('me', 'Some <b>bold</b> and <i>italic</i> text')
await client.send_message('me', 'An <a href="https://example.com">URL</a>')
# code and pre tags also work, but those break the documentation :)
await client.send_message('me', '<a href="tg://user?id=me">Mentions</a>')

# Explicit parse mode
# No parse mode by default
client.parse_mode = None

# ...but here I want markdown
await client.send_message('me', 'Hello, **world**!', parse_mode='md')

# ...and here I need HTML
await client.send_message('me', 'Hello, <i>world</i>!', parse_mode='html')

# If you logged in as a bot account, you can send buttons
from telethon import events, Button

@client.on(events.CallbackQuery)
async def callback(event):
    await event.edit('Thank you for clicking {}!'.format(event.data))

# Single inline button
await client.send_message(chat, 'A single button, with "clk1" as data',
                          buttons=Button.inline('Click me', b'clk1'))

# Matrix of inline buttons
await client.send_message(chat, 'Pick one from this grid', buttons=[
    [Button.inline('Left'), Button.inline('Right')],
    [Button.url('Check this site!', 'https://example.com')]
])

# Reply keyboard
await client.send_message(chat, 'Welcome', buttons=[
    Button.text('Thanks!', resize=True, single_use=True),
    Button.request_phone('Send phone'),
    Button.request_location('Send location')
])

# Forcing replies or clearing buttons.
await client.send_message(chat, 'Reply to me', buttons=Button.force_reply())
await client.send_message(chat, 'Bye Keyboard!', buttons=Button.clear())

# Scheduling a message to be sent after 5 minutes
from datetime import timedelta
await client.send_message(chat, 'Hi, future!', schedule=timedelta(minutes=5))
```

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

### Forward messages example

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

Shows how to forward a single message, multiple messages, and forward as a copy using send_message.

```python
# a single one
await client.forward_messages(chat, message)
# or
await client.forward_messages(chat, message_id, from_chat)
# or
await message.forward_to(chat)

# multiple
await client.forward_messages(chat, messages)
# or
await client.forward_messages(chat, message_ids, from_chat)

# Forwarding as a copy
await client.send_message(chat, message)
```

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

### Get tokens from BotFather using client.conversation

Source: https://docs.telethon.dev/en/stable/_sources/misc/changelog.rst.txt

Use the Conversation API to interact with a bot and extract tokens from code entities. The example shows how to send a command, click through menu items, and print the token from the final message.

```python
from telethon.tl import types

with client.conversation('BotFather') as conv:
    conv.send_message('/mybots')
    message = conv.get_response()
    message.click(0)
    message = conv.get_edit()
    message.click(0)
    message = conv.get_edit()
    for _, token in message.get_entities_text(types.MessageEntityCode):
        print(token)
```

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

### Access fields and call API functions

Source: https://docs.telethon.dev/en/stable/_sources/quick-references/faq.rst.txt

Access fields on Telethon objects using the dot operator, and call API functions with the client. The example shows getting the current user's username and fetching user photos.

```python
me = await client.get_me()
print(me.username)
#       ^ we used the dot operator to access the username attribute

result = await client(functions.photos.GetUserPhotosRequest(
    user_id='me',
    offset=0,
    max_id=0,
    limit=100
))
```

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

### Download a file and print its header

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

Demonstrates using download_file with bytes as the file argument to download in-memory and print the first 16 bytes. This is a low-level method; prefer download_media for typical use.

```python
# Download a file and print its header
data = await client.download_file(input_file, bytes)
print(data[:16])
```

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

### Basic conversation flow with get_response

Source: https://docs.telethon.dev/en/stable/modules/custom.html

Use this snippet to start a conversation, send a message, and wait for the user's response. The conversation context manager handles setup and cleanup. The response text is extracted from the returned Message object.

```python
async with client.conversation(...) as conv:
    await conv.send_message('Hey, what is your name?')

    response = await conv.get_response()
    name = response.text

    await conv.send_message('Nice to meet you, {}!'.format(name))

```

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

### Get entity and display name, iterate messages, get peer ID

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

Shows how to get an entity by username or 'me', display its name, get an input entity for efficient reuse, iterate messages, and get a peer ID from a phone number (must be in contacts).

```python
from telethon import utils

me = await client.get_entity('me')
print(utils.get_display_name(me))

chat = await client.get_input_entity('username')
async for message in client.iter_messages(chat):
    ...

# Note that you could have used the username directly, but it's
# good to use get_input_entity if you will reuse it a lot.
async for message in client.iter_messages('username'):
    ...

# Note that for this to work the phone number must be in your contacts
some_id = await client.get_peer_id('+34123456789')

```

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

### Create and run asyncio tasks with asyncio.create_task and asyncio.run

Source: https://docs.telethon.dev/en/stable/_sources/concepts/asyncio.rst.txt

Shows how to schedule two coroutines as tasks with asyncio.create_task and run them with asyncio.run. The first version includes explanatory comments; the second is the same example without comments.

```python
async def hello(delay):
    await asyncio.sleep(delay)  # await tells the loop this task is "busy"
    print('hello')  # eventually the loop resumes the code here

async def world(delay):
    # the loop decides this method should run first
    await asyncio.sleep(delay)  # await tells the loop this task is "busy"
    print('world')  # eventually the loop finishes all tasks

async def main():
    asyncio.create_task(world(2))  # create the world task, passing 2 as delay
    asyncio.create_task(hello(delay=1))  # another task, but with delay 1
    await asyncio.sleep(3)  # wait for three seconds before exiting

try:
    # create a new temporary asyncio loop and use it to run main
    asyncio.run(main())
except KeyboardInterrupt:
    pass
```

```python
import asyncio

async def hello(delay):
    await asyncio.sleep(delay)
    print('hello')

async def world(delay):
    await asyncio.sleep(delay)
    print('world')

async def main():
    asyncio.create_task(world(2))
    asyncio.create_task(hello(delay=1))
    await asyncio.sleep(3)

try:
    asyncio.run(main())
except KeyboardInterrupt:
    pass
```

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

### Install or upgrade Telethon with pip

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

Upgrade pip and install or upgrade the Telethon library to the latest stable version. Run these commands in a terminal with Python installed.

```sh
python3 -m pip install --upgrade pip
python3 -m pip install --upgrade telethon
```

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

### Create and use a TelegramClient

Source: https://docs.telethon.dev/en/stable/_sources/modules/client.rst.txt

Create a TelegramClient with your name, api_id, and api_hash, then run an async main function that sends a message to yourself. The `with client:` block ensures proper connection handling.

```python
from telethon import TelegramClient

client = TelegramClient(name, api_id, api_hash)

async def main():
    # Now you can use all client methods listed below, like for example...
    await client.send_message('me', 'Hello to myself!')

with client:
    client.loop.run_until_complete(main())
```

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

### Install optional dependencies for Telethon

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

Install common missing dependencies on apt-based systems, then install Telethon with optional packages cryptg and pillow for better performance and image handling.

```sh
apt update
apt install clang lib{jpeg-turbo,webp}-dev python{,-dev} zlib-dev
pip install -U --user setuptools
pip install -U --user telethon cryptg pillow
```
Tokens:
Raw