Telegram API - Telethon - краткая сводка — 2026

Published: 2026-08-06

Telethon — это мощная и популярная Python-библиотека для работы с Telegram API напрямую через протокол MTProto. В отличие от библиотек, построенных вокруг HTTP Bot API (например, python-telegram-bot), Telethon даёт полный доступ ко всем возможностям Telegram: от управления личным аккаунтом до создания полноценных пользовательских ботов и автоматизации на уровне, недоступном официальному Bot API.

На момент публикации этой сводки актуальной версией является Telethon 1.44.0 (выпущена 15 июня 2026 года). Библиотека распространяется под свободной лицензией MIT, разрабатывается и поддерживается сообществом, главным автором является Lonami Exo. Официальная документация доступна на docs.telethon.dev.

Что такое Telethon

Telegram — одно из самых популярных приложений для обмена сообщениями в мире, и его внутренний API (MTProto) является основой всех официальных и сторонних клиентов. Telethon — это обёртка, которая уже проделала «тяжёлую работу» по реализации протокола, шифрования, обработки обновлений и управления соединением, позволяя разработчику сосредоточиться на логике приложения.

Ключевая идея Telethon — управление обычным аккаунтом Telegram программно. В то время как официальный Bot API позволяет управлять только учётными записями ботов, Telethon может входить в систему как пользователь (по номеру телефона или через QR-код) и выполнять любые действия, доступные официальному клиенту:

отправка и получение сообщений;
чтение истории чатов и каналов;
работа с группами, супергруппами и каналами;
загрузка и скачивание файлов любых размеров;
получение информации о пользователях, сообщениях и чатах;
обработка новых сообщений в реальном времени через систему событий;
управление контактами, диалогами, реакциями, опросами и многим другим;
редактирование профиля, смена статуса «онлайн», просмотр «онлайн» других пользователей;
работа с лимитами и приглашениями, управление администраторами и правами.

Официальная документация описывает Telethon так: «Think of it as a wrapper that has already done the heavy job for you» — «воспринимайте её как обёртку, которая уже сделала тяжёлую работу за вас».

История и экосистема

Telethon существует с 2015 года и пережил несколько крупных версий:

до версии 1.0 использовался синхронный подход, а API строилось вокруг простых функций;
начиная с версии 1.0 (2020 год) библиотека была переписана вокруг asyncio и стала полностью асинхронной;
для удобства сохранена совместимость: режим `telethon.sync` позволяет писать код почти как в старых версиях, автоматически оборачивая корутины в синхронные вызовы;
выходные версии нумеруются по схеме 1.x.y: например, 1.42, 1.43.0, 1.43.1, 1.43.2, а затем 1.44.0 в июне 2026 года.

Экосистема вокруг Telethon включает:

tl.telethon.dev — полный справочник всех методов и типов MTProto-схемы Telegram, сгенерированный автоматически;
расширение cryptg — C-реализация криптографии для значительного ускорения;
множество сторонних проектов: Telethon-based фреймворки, клиенты, парсеры и утилиты.

Исходный код библиотеки хранится на Codeberg (ранее GitHub), баги сообщают в систему трекинга проекта.

MTProto и Bot API: в чём разница

Чтобы понять ценность Telethon, важно различать два способа общения с Telegram:

HTTP Bot API

Bot API — официальный способ управления ботами. Это обычный HTTP-интерфейс: разработчик отправляет JSON-запросы на серверы Telegram, а те транслируют их во внутренние MTProto-вызовы через TDLib. Настройка бота (команды, имя, аватар) выполняется через @BotFather.

Особенности Bot API:

управляет только ботами, завести сессию обычного пользователя нельзя;
ограниченный набор методов (нет работы с реакциями в некоторых старых версиях, ограничена работа с группами и т. п.);
не имеет встроенного механизма «живых» обновлений в реальном времени — только long polling или webhooks;
файлы ограничены рамками API (до 50 МБ при загрузке через сам API в отдельных случаях, до 20 МБ при скачивании через обычный метод).

MTProto

MTProto — собственный протокол Telegram для связи клиентов с серверами. По нему работают все официальные приложения, и он открыт для сторонних клиентов. Telethon — это альтернативный бэкенд на MTProto, полностью написанный на Python, который значительно проще в настройке и использовании, чем TDLib.

Преимущества MTProto-клиентов (и Telethon в частности):

вход как пользователь по номеру телефона или QR-коду, а также как бот через токен;
прямой доступ ко всем функциям клиента: статусы «онлайн», реакции, опросы, стикеры, премиум-особенности;
эффективная работа с обновлениями через постоянное соединение (без long polling и webhook'ов);
работа с файлами до 2 ГБ и более с возможностью продолжения загрузки;
меньше накладных расходов — одна сессия обрабатывает все события сразу.

Сравнение Telethon и Bot API
Параметр	Telethon (MTProto)	Bot API (HTTP)
Тип аккаунта	Пользователь и бот	Только бот
Протокол	MTProto напрямую	HTTP через TDLib
Обновления в реальном времени	События через постоянное соединение	Long polling / webhooks
Работа с файлами	До 2 ГБ, с докачкой	Ограничения API
Статус «онлайн», реакции, премиум	Доступны	Частично или недоступны
Скорость запуска	Быстро (чистый Python)	Зависит от TDLib (библиотека на C++)
Сложность настройки	Низкая	Низкая

Установка

Telethon требует Python 3 (поддерживаются все современные версии, включая 3.8–3.13+). Установка выполняется стандартными средствами pip:

python3 -m pip install --upgrade pip
python3 -m pip install --upgrade telethon

Проверка установки:

python3 -c "import telethon; print(telethon.__version__)"

В выводе должна появиться версия, например `1.44.0`.

Установка dev-версии

Если нужны самые свежие (ещё не выпущенные) изменения, можно установить напрямую из репозитория:

python3 -m pip install --upgrade https://codeberg.org/Lonami/Telethon/archive/v1.zip

Официальная документация предупреждает: dev-версия может содержать ошибки и не рекомендуется для продакшена, однако при сообщении о баге рекомендуется проверить, воспроизводится ли проблема именно в ней.

Дополнительные зависимости

Для ускорения и расширения функциональности рекомендуется установить:

cryptg — криптография на C вместо Python, ускорение шифрования/дешифрования в разы (от сотен килобайт до нескольких мегабайт в секунду при загрузке/скачивании файлов). Если cryptg не установлен, используется более медленный чистый Python-модуль pyaes;
Pillow — для работы с изображениями (например, изменение размеров фото перед отправкой);
cryptg и асинхронные реализации — выбор реализации криптографии.

Получение api_id и api_hash

Перед началом работы с Telethon необходимо получить собственный API ID и API hash. Они выдаются для вашего приложения (не для телефона) на сайте my.telegram.org и могут использоваться с любым номером телефона или даже для бот-аккаунтов.

Порядок действий:

Зайти на my.telegram.org и войти с номером телефона аккаунта разработчика;
Нажать на пункт API development tools;
Откроется окно Create new application — заполнить данные приложения (URL указывать не обязательно; позднее можно изменить только первые два поля — App title и Short name);
Нажать Create application.

Официальное предупреждение: API hash является секретом, Telegram не позволяет отозвать его, поэтому нельзя публиковать его в открытых репозиториях, чатах или скриншотах.

Первая программа: вход и отправка сообщения

Простейший пример из официальной документации — отправить самому себе сообщение «Hello, myself!»:

from telethon import TelegramClient

# Подставьте свои значения с my.telegram.org
api_id = 12345
api_hash = '0123456789abcdef0123456789abcdef'

# Первый параметр — имя .session файла (допустимы абсолютные пути)
with TelegramClient('anon', api_id, api_hash) as client:
    client.loop.run_until_complete(client.send_message('me', 'Hello, myself!'))

При первом запуске Telethon запросит телефонный номер и код подтверждения (или предложит вход по QR-коду). После успешного входа создаётся файл сессии (например, `anon.session`), который содержит ключи авторизации, поэтому при последующих запусках ввод пароля не требуется.

Современный асинхронный стиль выглядит так:

from telethon import TelegramClient

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

async def main():
    await client.start()
    await client.send_message('me', 'Привет, я!')
    await client.disconnect()

import asyncio
asyncio.run(main())

Важное замечание из документации: не называйте свой скрипт `telethon.py` — иначе Python попытается импортировать клиент из вашего файла и выдаст ошибку «ImportError: cannot import name 'TelegramClient'».

Авторизация

Telethon поддерживает несколько способов входа:

по номеру телефона с кодом из SMS или звонка;
по QR-коду (удобно для аккаунтов с двухфакторной аутентификацией);
для ботов — по токену, полученному от @BotFather.

Основные методы авторизации из Client Reference:

`start()` — запускает клиент: подключается к серверам Telegram и выполняет вход, если это необходимо;
`send_code_request()` — отправляет код подтверждения на указанный номер телефона;
`sign_in()` — выполняет вход в существующий аккаунт пользователя или бота;
`qr_login()` — запускает вход по QR-коду;
`sign_up()` — регистрация нового аккаунта.

Поддерживается двухфакторная аутентификация: если у аккаунта задан пароль, Telethon спросит его при входе, а значение может быть передано в параметрах.

Сессии

Сессия — это набор данных авторизации (auth key), хранящийся локально. По умолчанию Telethon сохраняет сессию в файл, но поддерживаются и другие бэкенды (SQLite, в памяти, в базе данных). Одна и та же сессия может использоваться с разными API ID, а один API ID — с разными аккаунтами.

Базовые операции: сообщения и диалоги

Отправка сообщений

Основной метод — `send_message(entity, message)`, где entity — получатель: username, номер телефона, ссылка-приглашение, ID пользователя или объект чата.

await client.send_message('username', 'Привет!')
await client.send_message(123456789, 'Сообщение по ID')
await client.send_message('https://t.me/joinchat/...', 'В группу по ссылке')

Также доступны:

`send_file()` — отправка файлов, изображений, документов, голосовых сообщений;
`edit_message()` — редактирование уже отправленных сообщений;
`delete_messages()` — удаление сообщений;
`forward_messages()` — пересылка сообщений в другие чаты;
`send_poll()` — отправка опросов.

Чтение истории

`get_messages()` — получение истории чата с поддержкой пагинации и фильтрации (по типу сообщений, ключевым словам, временным промежуткам).

messages = await client.get_messages('channel', limit=100)
for message in messages:
    print(message.sender_id, message.text)

Метод `iter_messages()` возвращает асинхронный итератор, позволяя перебирать всю историю без загрузки в память — это основа для парсинга больших каналов.

Диалоги

`get_dialogs()` — список всех чатов, групп и каналов, в которых состоит аккаунт. Через диалоги можно узнать непрочитанные сообщения, черновики, закреплённые чаты и другую информацию.

События: обработка в реальном времени

Одна из главных особенностей Telethon — обработка новых событий через декораторы. Классический пример из главной страницы документации:

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()

Доступные типы событий:

`events.NewMessage` — новое сообщение (включая личные, групповые, канальные);
`events.MessageEdited` — редактирование сообщения;
`events.MessageDeleted` — удаление сообщения;
`events.ChatAction` — действия в чате (вступление, выход, изменение названия и т. п.);
`events.UserUpdate` — изменения в пользователях (фото, статус, имя);
`events.CallbackQuery` — нажатия на inline-кнопки;
`events.InlineQuery` — inline-запросы;
`events.Album` — альбомы (медиагруппы);
`events.StopPropagation` — механизм остановки обработки.

Фильтры событий позволяют реагировать только на определённые чаты, отправителей или текст (через regex-паттерны, как в примере с `(?i).*Hello`).

Работа с чатами, группами, каналами и пользователями

Telethon предоставляет полный набор методов для управления диалогами:

`get_entity()` — получение информации об объекте (пользователе, чате, канале) по имени, ID или ссылке;
`get_participants()` — список участников группы или канала (с фильтрами по ролям: администраторы, забаненные и т. д.);
`get_permissions()` / `edit_permissions()` — просмотр и изменение прав участников;
`create_group()` / `create_supergroup()` / `create_channel()` — создание групп и каналов;
`edit_admin()` — назначение и изменение прав администраторов;
`kick_participant()` — исключение участников;
`invite_participants()` — приглашение участников;
`join_channel()` / `leave_channel()` — вступление и выход из каналов;
`pin_message()` — закрепление сообщений;
`get_profile_photos()` / `download_profile_photo()` — фотографии профиля;
`get_me()` — информация о собственном аккаунте;
`get_common_chats()` — общие чаты двух пользователей.

Получение информации о сообщениях

Каждое сообщение (`Message`) содержит: текст, отправителя, время, ответы, реакции, медиафайлы, кнопки, ссылки и т. д. Через методы сообщения можно отвечать, пересылать, редактировать, удалять, ставить реакции и подписываться на события.

Медиафайлы: загрузка и скачивание

Telethon умеет работать с файлами вплоть до лимитов Telegram (файлы до 2 ГБ с поддержкой продолжения загрузки):

`send_file()` — отправка файлов по пути, по URL, из байтов, из потоков;
`download_media()` — скачивание медиафайла из сообщения;
`download_profile_photo()` — скачивание фото профиля;
`upload_file()` — предварительная загрузка файла в «медиа-библиотеку» Telegram.

Пример скачивания вложений из последних сообщений:

async for message in client.iter_messages('channel', limit=50):
    if message.media:
        await message.download_media(file='downloads/')

При установке cryptg скорость передачи файлов может вырасти в десятки раз.

Расширенные возможности

Реакции

Telethon поддерживает реакции на сообщения (включая премиум-реакции) через `react()` на объекте сообщения или метод `send_reaction()`.

Опросы и викторины

`send_poll()` позволяет создавать опросы и викторины с несколькими вариантами ответа, анонимностью и выбором времени.

Контакты

`get_contacts()` — список контактов;
`add_contact()` / `delete_contacts()` — управление контактами;
`import_contacts()` — импорт из телефонной книги.

Профиль

`edit_profile()` — изменение имени, фамилии, описания «о себе»;
`send_code_request()` / `sign_in()` — смена активного номера;
`update_username()` — изменение username;
`get_me()` — собственная анкета.

Админ-инструменты

`edit_admin()`, `edit_permissions()` — управление правами;
`ban_user()` / `unban_user()` — блокировка и разблокировка;
`delete_channel()` / `delete_supergroup()` — удаление диалогов;
`invite_to_channel()` — массовые приглашения;
`get_message_history()` — история сообщений.

Работа с онлайн-статусами и премиумом

Через MTProto доступны статусы «онлайн», последнее посещение, а также возможности, связанные с Telegram Premium (эмодзи-статусы, премиум-реакции и др.).

Зачем используют Telethon: сценарии применения

Автоматизация личного аккаунта — автопостинг, автоответы, статистика;
Создание пользовательских ботов — боты с функциями, недоступными Bot API (работа с «онлайн», реакции, профили пользователей);
Парсинг каналов и чатов — сбор контента, участников, статистики для аналитики и маркетинга;
Мониторинг сообщений по ключевым словам — мгновенное оповещение при появлении нужного слова в чатах и каналах;
Массовая рассылка — в рамках официальных ограничений Telegram (см. ниже);
Архивирование переписки — сохранение истории чатов в базу данных или файлы;
Интеграция Telegram с другими сервисами — мосты, уведомления, синхронизация с CRM, ERP и мессенджерами;
Тестирование и разработка клиентов — эксперименты с MTProto-методами.

Ограничения и правила безопасности

Важно понимать, что автоматизация аккаунтов Telegram регулируется Правилами использования API. Основные ограничения:

нельзя спамить: массовые рассылки без согласия получателей приводят к блокировке аккаунта;
количество сообщений и действий в единицу времени ограничено (rate limits);
вступление в большое число чатов и приглашения участников также ограничиваются;
не рекомендуется использовать личный аккаунт для масштабной автоматизации — есть риск ограничения.

Для ботов лимиты несколько отличаются от пользовательских, но базовые принципы («не спамить») действуют для всех.

Безопасность

Никогда не публикуйте api_hash и файлы .session — они дают полный доступ к аккаунту;
храните секреты в переменных окружения;
используйте отдельные сессии для разных целей;
ограничивайте число одновременных активных сессий: Telegram допускает несколько активных сессий, но каждая из них видна как отдельное «устройство»;
при работе с большим числом запросов добавляйте паузы и обрабатывайте исключения `FloodWaitError` — Telethon умеет автоматически ждать, если Telegram запросил паузу.

Производительность и оптимизация

установка cryptg ускоряет шифрование и передачу файлов в разы;
использование асинхронного стиля (`async/await`) позволяет обрабатывать много событий одновременно;
`iter_*` методы вместо `get_*` экономят память при работе с большими наборами данных;
пагинация и фильтрация запросов снижают нагрузку на API;
если ваша задача — только боты, рассмотрите и Bot API: для простых сценариев он проще, но при росте требований Telethon часто оказывается единственным решением.

Сравнение с альтернативами

Сравнение Telethon с другими библиотеками
Библиотека	Протокол	Тип аккаунта	Стиль	Особенности
Telethon	MTProto (Python)	Пользователь + бот	asyncio (+sync режим)	Богатая экосистема, события, справочник на tl.telethon.dev
Pyrogram	MTProto (на базе MTProtoKit/Pyrogram)	Пользователь + бот	asyncio	Популярная альтернатива, схожие возможности
python-telegram-bot	HTTP Bot API	Только бот	asyncio	Официальная обёртка над Bot API, богатая документация
aiogram	HTTP Bot API	Только бот	asyncio	Быстрый фреймворк с маршрутизацией и FSM
TeleBot (pyTelegramBotAPI)	HTTP Bot API	Только бот	Синхронный	Простота и популярность в учебных проектах
TDLib	MTProto (нативный C++)	Пользователь + бот	События через JSON	Официальная низкоуровневая библиотека Telegram

Когда выбирать Telethon

нужен доступ к функциям пользовательского аккаунта;
требуется обработка событий в реальном времени без webhook'ов;
нужны файлы большого размера или работа с медиа-библиотекой;
планируется парсинг, мониторинг, автоматизация личного аккаунта;
важна полнота контроля над MTProto-методами.

Когда достаточно Bot API

создаётся обычный бот с командами и клавиатурами;
не нужны функции пользовательского аккаунта;
приемлемы long polling или webhooks;
важен минимальный размер зависимостей.

Работа с документацией

Официальная документация (docs.telethon.dev) структурирована следующим образом:

Installation — установка и настройка;
Signing In — авторизация и первый запуск;
Client Reference — краткая сводка всех важных методов и свойств класса `TelegramClient`, отсортированных по релевантности;
Modules — подробное описание всех модулей: client, messages, chats, uploads, downloads, updates, telegram и другие;
Quick References — быстрые справки по клиенту, сообщениям, чатам, файлам и т. д.;
Misc — история версий (Changelog), совместимость и удобство (Compatibility and Convenience), часто задаваемые вопросы;
tl.telethon.dev — автоматически сгенерированный полный справочник методов и типов схемы MTProto.

Рекомендуемый порядок изучения: установка → вход в систему → отправка первого сообщения → события → работа с чатами → медиафайлы → продвинутые темы.

Резюме

Telethon — зрелая, активно развивающаяся Python-библиотека (актуальная версия 1.44.0, июнь 2026) для работы с Telegram через протокол MTProto. Она позволяет автоматизировать личные аккаунты и ботов, получать сообщения в реальном времени, парсить каналы и чаты, работать с файлами большого размера и использовать функции Telegram, недоступные через официальный HTTP Bot API. Установка проста (pip install telethon), вход выполняется по номеру телефона, QR-коду или токену бота, а для ускорения рекомендуется установить cryptg. Telethon остаётся оптимальным выбором для задач автоматизации, парсинга и создания «пользовательских» ботов, тогда как для классических ботов можно ограничиться Bot API.

Ссылки

×