whatisgithub

What is telethon?

lonamiwebs/telethon — explained in plain English

Analysis updated 2026-06-24

★ 11,976PythonAudience · developerComplexity · 2/5Setup · moderate

In one sentence

Telethon is a Python library for automating Telegram, send messages, download media, or build bots using Telegram's full low-level protocol instead of the limited official Bot API.

Mindmap

mindmap
  root((Telethon))
    What it does
      Telegram automation
      Send messages
      Download media
      Listen for events
    Tech Stack
      Python
      asyncio
      MTProto
    Use Cases
      Telegram bots
      Media downloader
      Message monitor
    Audience
      Python developers
      Bot builders
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

What do people build with it?

USE CASE 1

Write a Python script that automatically sends Telegram messages or photos on a schedule.

USE CASE 2

Build a Telegram bot that accesses features unavailable through the standard Bot API by using a full user account.

USE CASE 3

Download media files from Telegram chats programmatically using Python async code.

USE CASE 4

Monitor a Telegram group for new messages and trigger custom actions based on their content.

What is it built with?

PythonasyncioMTProtopip

How does it compare?

lonamiwebs/telethoncoleifer/peeweeh2oai/h2ogpt
Stars11,97611,96711,989
LanguagePythonPythonPython
Setup difficultymoderateeasyhard
Complexity2/52/54/5
Audiencedeveloperdeveloperdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · moderate Time to first run · 30min

Requires a Telegram API key (api_id and api_hash) obtained from Telegram's developer portal before any code can run.

So what is it?

Telethon is a Python library that lets you write programs that interact with Telegram, the messaging app. It talks directly to Telegram using the platform's own low-level protocol (called MTProto), rather than going through the more limited official Bot API. This means you can use it both as a regular user account and as a bot, giving it access to a wider range of Telegram features than the standard bot interface allows. The library is built around Python's async/await system, which is a way of writing code that handles multiple things at once without blocking. A basic setup involves creating a client object with your Telegram API credentials (which you obtain from Telegram's developer portal), logging in, and then making calls to read or send data. The README shows short examples: sending a text message, sending a photo, and downloading media from a received message. Installation is a single pip command. The README is brief and points to external documentation for more detailed examples, troubleshooting, and advanced usage. One important note from the README: version 2.0 of Telethon introduced breaking changes compared to earlier versions. Anyone using older Telethon code is advised to read the migration guide before upgrading. The README also warns that using any third-party Telegram library carries a risk of account suspension if the usage violates Telegram's terms of service, so care is needed when automating user accounts.

Copy-paste prompts

Prompt 1
I have Telethon installed and my Telegram API credentials ready. Show me an async Python script that logs in and sends a message to a specific contact.
Prompt 2
How do I use Telethon to download all photos from a specific Telegram group and save them to a local folder?
Prompt 3
I'm migrating from Telethon 1.x to 2.0. What are the breaking changes and what do I need to update in my code?
Prompt 4
Write a Telethon script that listens for new messages in a Telegram channel and prints each one to the console in real time.
Prompt 5
Why does using Telethon's MTProto access give me more capabilities than the standard Telegram Bot API?

Frequently asked questions

What is telethon?

Telethon is a Python library for automating Telegram, send messages, download media, or build bots using Telegram's full low-level protocol instead of the limited official Bot API.

What language is telethon written in?

Mainly Python. The stack also includes Python, asyncio, MTProto.

How hard is telethon to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is telethon for?

Mainly developer.

Open on GitHub → Ask about another repo

This repo across BitVibe Labs

Verify against the repo before relying on details.

What are similar repos?