Telethon README

The project's README from github.com/LonamiWebs/Telethon. As one markdown file: README.md.

Moved to https://codeberg.org/Lonami/Telethon. The GitHub repository may be deleted in the future.

Telethon

.. epigraph::

⭐️ Thanks everyone who has starred the project, it means a lot!

|logo| Telethon is an asyncio_ Python 3 MTProto_ library to interact with Telegram_'s API as a user or through a bot account (bot API alternative).

.. important::

If you have code using Telethon before its 1.0 version, you must
read `Compatibility and Convenience`_ to learn how to migrate.
As with any third-party library for Telegram, be careful not to
break `Telegram's ToS`_ or `Telegram can ban the account`_.

What is this?

Telegram is a popular messaging application. This library is meant to make it easy for you to write Python programs that can interact with Telegram. Think of it as a wrapper that has already done the heavy job for you, so you can focus on developing an application.

Installing

.. code-block:: sh

pip3 install telethon

Creating a client

.. code-block:: python

from telethon import TelegramClient, events, sync

# These example values won't work. You must get your own api_id and
# api_hash from https://my.telegram.org, under API Development.
api_id = 12345
api_hash = '0123456789abcdef0123456789abcdef'

client = TelegramClient('session_name', api_id, api_hash)
client.start()

Doing stuff

.. code-block:: python

print(client.get_me().stringify())

client.send_message('username', 'Hello! Talking to you from Telethon')
client.send_file('username', '/home/myself/Pictures/holidays.jpg')

client.download_profile_photo('me')
messages = client.get_messages('username')
messages[0].download_media()

@client.on(events.NewMessage(pattern='(?i)hi|hello'))
async def handler(event):
    await event.respond('Hey!')

Next steps

Do you like how Telethon looks? Check out Read The Docs_ for a more in-depth explanation, with examples, troubleshooting issues, and more useful information.

.. _asyncio: https://docs.python.org/3/library/asyncio.html .. _MTProto: https://core.telegram.org/mtproto .. _Telegram: https://telegram.org .. _Compatibility and Convenience: https://docs.telethon.dev/en/stable/misc/compatibility-and-convenience.html .. _Telegram's ToS: https://core.telegram.org/api/terms .. _Telegram can ban the account: https://docs.telethon.dev/en/stable/quick-references/faq.html#my-account-was-deleted-limited-when-using-the-library .. _Read The Docs: https://docs.telethon.dev

.. |logo| image:: logo.svg :width: 24pt :height: 24pt

Telethon (LonamiWebs/Telethon)

client
Searching Database…

12.1K ·GitHub
Telethon
archived
What is this?Telethon is an asyncio Python 3 MTProto library for talking directly to Telegram's API, letting you act as a full user account or as a bot.
Is this a wrapper around Telegram's Bot API, or something different?It talks to Telegram's native MTProto protocol directly rather than wrapping the official Bot API, handling the protocol work for you so you can just write a normal Python program.
How do I install it and get a client running?Install with 'pip3 install telethon', then create a TelegramClient with a session name plus your api_id and api_hash, and call client.start().
Do I need a Telegram API ID and hash before I start?Yes, you need your own api_id and api_hash from Telegram's API Development page; the example values in the README won't work.
Is this project still maintained?No, the repository is archived and the README states it has moved and may be deleted in the future, so don't expect fixes or updates here.
Can Telethon log in as both a regular user and a bot?Yes, it can authenticate as a full Telegram user account or as a bot account, giving access to more than just the official Bot API.
Does it support async/await event handling?Yes, it's built on asyncio and lets you write async handlers, e.g. decorating a function with @client.on(events.NewMessage(pattern=...)) to react to incoming messages.
Is there a risk of getting my account banned?Yes, since it's a third-party client, misusing it can break Telegram's Terms of Service and result in the account being banned.
What can it do out of the box?Send and receive messages, send or download files and media, fetch profile photos, and read message history with just a few lines of code.
What are similar projects?python-telegram-bot, ItChat, wxpy, discord.py, fragment-api-dev, whatsapp-web.js, httpx, botkit
Which topics is it in?mtproto, asyncio, client, api-client, bot, python3, messaging, python-library, telegram, chatbot, deprecated, sdk
Creator
LonamiWebs
Size
9.6 MB
Stars
12.1K
Updated
CommitFeb 21
Age
10y
Commits · 90 Days