Прокси для Telegram-ботов: Bot API, aiogram, Telethon и Pyrogram

Прокси для Telegram-бота нужен, когда сервер не может достучаться до Telegram напрямую или обязан выходить в сеть через один разрешённый адрес. Во всех популярных Python-библиотеках это решается одним параметром: URL прокси в python-telegram-bot и aiogram, словарь или кортеж в Telethon, словарь в Pyrogram. А вот лимиты Telegram прокси не снимает: они считаются по боту и по чату, а не по IP.

Разберём, когда прокси действительно помогает, как ведут себя long polling и вебхуки, приведём рабочие примеры для четырёх библиотек и покажем, как правильно обрабатывать ошибку 429 Too Many Requests, не заваливая сервер повторами.

Когда боту нужен прокси

• Сервер не видит Telegram. В некоторых регионах хостинга, офисных и учебных сетях api.telegram.org или дата-центры MTProto фильтруются. Посредник за пределами этой сети возвращает связь.
• Исходящий трафик должен идти с одного известного IP. Корпоративные файрволы часто выпускают серверы наружу только через согласованный шлюз, а сторонние API, к которым обращается бот, иногда принимают запросы лишь с адреса из белого списка.
• На одном сервере живут несколько ботов, и вы хотите развести их исходящий трафик для мониторинга или чтобы один шумный бот не мешал остальным.

Если ничего из этого не про вас, запускайте бота без прокси: каждый лишний узел добавляет задержку и ещё одну точку отказа.

Bot API или MTProto-клиенты

Python-код общается с Telegram двумя способами, и прокси в них подключается по-разному.

Библиотекам Bot API подойдёт любой надёжный HTTP- или SOCKS5-прокси. Для MTProto-библиотек надёжнее SOCKS5, потому что это не обычный HTTPS-трафик. Если не уверены, какой порт просить у провайдера, посмотрите разбор SOCKS5 и HTTP-прокси.

Long polling и вебхуки за прокси

В режиме long polling бот сам раз за разом запрашивает у Telegram новые события методом getUpdates. И опрос, и все исходящие вызовы вроде sendMessage начинает ваш сервер, поэтому прокси покрывает весь обмен.

В режиме вебхука Telegram сам отправляет события на ваш публичный HTTPS-адрес. Прокси на стороне бота в этом входящем потоке не участвует: эндпоинт должен быть доступен из интернета на порту 443, 80, 88 или 8443, как требует Bot API. Для ответов, которые код отправляет обычными вызовами API, прокси по-прежнему работает.

Настройка в python-telegram-bot

Начиная с версии 20.7 у сборщика приложения две отдельные настройки: proxy() для обычных вызовов API и get_updates_proxy() для опроса. Если нет причины их разделять, указывайте один и тот же адрес. Поддержка SOCKS ставится как дополнительная зависимость:

pip install "python-telegram-bot[socks]"

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

RELAY = "socks5://botops:Qx7-pass@203.0.113.40:1080"

async def health(update: Update, ctx: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text("alive")

bot_app = (
    ApplicationBuilder()
    .token("000000:replace-with-your-token")
    .proxy(RELAY)
    .get_updates_proxy(RELAY)
    .build()
)
bot_app.add_handler(CommandHandler("health", health))
bot_app.run_polling()

Старые методы proxy_url() и get_updates_proxy_url() объявлены устаревшими, так что при обновлении кода замените их.

Настройка в aiogram 3

В aiogram все запросы идут через объект сессии. Передайте URL прокси в AiohttpSession, а сессию — в Bot. Для SOCKS рядом с aiogram должен стоять пакет aiohttp-socks.

import asyncio
from aiogram import Bot, Dispatcher
from aiogram.client.session.aiohttp import AiohttpSession
from aiogram.filters import Command
from aiogram.types import Message

relay_session = AiohttpSession(proxy="socks5://botops:Qx7-pass@203.0.113.40:1080")
courier = Bot(token="000000:replace-with-your-token", session=relay_session)
router = Dispatcher()

@router.message(Command("health"))
async def health(msg: Message) -> None:
    await msg.answer("alive")

async def run() -> None:
    await router.start_polling(courier)

asyncio.run(run())

По документации aiogram логин и пароль можно указать прямо в URL или передать объектом aiohttp.BasicAuth, а цепочки прокси из aiohttp-socks тоже поддерживаются.

Настройка в Telethon

Для SOCKS- и HTTP-прокси Telethon принимает словарь и требует установленный python-socks[asyncio]. Без него библиотека лишь пишет предупреждение и не останавливается, а в длинных логах это легко пропустить.

from telethon import TelegramClient

API_ID = 1234567
API_HASH = "replace-with-your-hash"

relay = {
    "proxy_type": "socks5",
    "addr": "203.0.113.40",
    "port": 1080,
    "username": "botops",
    "password": "Qx7-pass",
    "rdns": True,
}

client = TelegramClient("ops-bot", API_ID, API_HASH, proxy=relay)
client.start(bot_token="000000:replace-with-your-token")
client.run_until_disconnected()

Из четырёх библиотек только Telethon умеет работать с MTProxy. Для этого нужен особый класс соединения и кортеж из хоста, порта и секрета:

from telethon import TelegramClient, connection

client = TelegramClient(
    "ops-bot", API_ID, API_HASH,
    connection=connection.ConnectionTcpMTProxyRandomizedIntermediate,
    proxy=("mtp.example.net", 443, "replace-with-secret"),
)

Что такое секрет MTProxy и чем отличаются префиксы dd и ee, рассказано в статье про MTProto-прокси.

Настройка в Pyrogram

Оригинальный репозиторий Pyrogram заархивирован в декабре 2024 года и больше не обновляется. Форки вроде Kurigram позиционируют себя как прямую замену и сохраняют те же аргументы Client, так что пример ниже должен работать и в них, но документацию форка всё же сверьте.

from pyrogram import Client

relay = dict(
    scheme="socks5",
    hostname="203.0.113.40",
    port=1080,
    username="botops",
    password="Qx7-pass",
)

app = Client(
    "ops-bot",
    api_id=1234567,
    api_hash="replace-with-your-hash",
    bot_token="000000:replace-with-your-token",
    proxy=relay,
)
app.run()

Pyrogram принимает схемы socks4, socks5 и http. Режима MTProxy в нём нет.

Как убедиться, что трафик идёт через прокси

Прежде чем винить библиотеку, проверьте, что сам прокси достаёт до Bot API. Один вызов curl с вашим токеном вернёт профиль бота, если всё в порядке:

curl -x "socks5h://botops:Qx7-pass@203.0.113.40:1080" "https://api.telegram.org/bot<TOKEN>/getMe"

Ответ JSON с "ok":true значит, что маршрут рабочий. Тайм-аут указывает на прокси или файрвол, а 401 Unauthorized — на неверный токен, а не на прокси. Сервер можно также прогнать через наш бесплатный чекер прокси.

Обработка ошибки 429 Too Many Requests

Telegram отвечает 429, когда бот шлёт слишком часто, и добавляет retry_after — сколько секунд нужно подождать. Официальные ориентиры такие: около одного сообщения в секунду в одном чате, до 20 сообщений в минуту в группе и примерно 30 сообщений в секунду суммарно при массовой рассылке уведомлений.

Смена или ротация прокси тут ничего не даёт. Лимиты привязаны к токену бота и к чату-получателю, поэтому с нового IP придёт та же 429. Решение одно: снизить темп и выдерживать retry_after.

Каждая библиотека отдаёт это значение:

Небольшая обёртка для aiogram, которая ждёт и повторяет отправку ограниченное число раз:

import asyncio
from aiogram.exceptions import TelegramRetryAfter

async def deliver(courier, chat_id: int, body: str, tries: int = 4):
    for _ in range(tries):
        try:
            return await courier.send_message(chat_id, body)
        except TelegramRetryAfter as slow_down:
            await asyncio.sleep(slow_down.retry_after + 1)
    raise RuntimeError(f"chat {chat_id}: still limited after {tries} tries")

В python-telegram-bot есть готовый ограничитель. Поставьте зависимость rate-limiter и добавьте в сборщик .rate_limiter(AIORateLimiter(max_retries=3)): он сам распределяет вызовы во времени и повторяет запрос после RetryAfter. Telethon короткие паузы выдерживает автоматически: всё, что меньше flood_sleep_threshold (по умолчанию 60 секунд), обрабатывается без исключения.

Какой прокси подходит боту

Бот — это процесс, который работает неделями, поэтому ему нужно соединение, которое не меняется:

• Статические прокси дата-центра или ISP дают постоянный адрес с низкой задержкой, и это вариант по умолчанию. Наши статические прокси сохраняют один IP на весь срок аренды.
• SOCKS5 с логином и паролем работает во всех четырёх библиотеках и в MTProto-клиентах. Привязку по IP лучше не использовать, если бот может переезжать между серверами.
• Ротируемые резидентские IP ничего не дают Bot API-боту и могут вызвать дополнительные проверки безопасности у MTProto-сессии, которая вдруг появилась из другого города.

Как подключить прокси в самом приложении, а не в коде, описано в инструкции по настройке прокси в Telegram.

Частые ошибки

httpx.ConnectError или ProxyError при старте. Неверный хост, порт или схема. Порт для HTTP не ответит на SOCKS5-запрос, и наоборот.

URL с SOCKS отклоняется с ошибкой импорта. Не установлена дополнительная зависимость: python-telegram-bot[socks], aiohttp-socks или python-socks[asyncio].

Опрос работает, а ответы падают по тайм-ауту. В python-telegram-bot задан только get_updates_proxy(). Добавьте ещё proxy().

Вебхук не получает события. Для входящего трафика прокси не важен. Проверьте сертификат, порт и вывод getWebhookInfo.

Telethon игнорирует прокси. Найдите в логах предупреждение про python-socks и установите пакет.