Telegram Bot API через прокси: настройка длинного поллинга, вебхуков и обработки ошибки 429

Введение: что вы получите от этого гайда

Если вы хотя бы раз запускали бота в Telegram, то знаете одну неприятную вещь. Сам бот пишется за вечер, а вот его стабильная работа превращается в отдельный проект. Сообщения приходят с задержкой, обновления теряются, сервер внезапно получает ошибку 429, а вебхук просто перестает вызываться без объяснений. Добавьте сюда прокси, через который обязаны идти все запросы, и количество точек отказа удваивается.

Этот пошаговый гайд закрывает именно эти проблемы. Вы научитесь работать с Telegram Bot API через прокси-сервер так, чтобы бот не падал, не терял сообщения и корректно реагировал на лимиты. Мы не будем разбирать протокол MTProto и не будем строить систему мониторинга прокси. Наша тема уже и практичнее: HTTP-запросы к api.telegram.org через прокси, два способа получения обновлений и правильная реакция на ограничения.

Что вы получите в итоге

• Рабочего бота, который отправляет запросы к Telegram Bot API через ваш прокси (HTTP или SOCKS5).
• Настроенный длинный поллинг, который не рвется на таймаутах и не дублирует сообщения.
• Вебхук с HTTPS и секретным токеном, принимающий обновления на вашем сервере.
• Готовую обертку для запросов, которая сама ждет нужное время при ошибке 429 и повторяет отправку.
• Понимание, какой режим выбрать для вашего проекта: поллинг или вебхук.

Для кого этот гайд

Для маркетологов и арбитражников, которые собирают ботов для рассылок, уведомлений о лидах и статистики по кампаниям. Для разработчиков, которым нужен фиксированный и предсказуемый исходящий IP для серверных запросов. Для владельцев бизнеса, чьи боты обслуживают клиентов и не имеют права молчать по часу. Если вы работаете с мобильными прокси и хотите пустить через них трафик бота, вы попали по адресу.

Что нужно знать заранее

Мы объясняем каждый шаг с нуля, но несколько базовых навыков сильно упростят жизнь. Полезно уметь открывать терминал или командную строку, копировать команды и запускать скрипты на Python. Знать, что такое HTTP-запрос и JSON, желательно, но мы напомним простыми словами. Продвинутые темы вынесены в отдельный раздел, начинающим можно его пропустить без потери результата.

Сколько времени потребуется

Подготовка и создание бота займут около 20 минут. Настройка прокси и первый успешный запрос еще 20-30 минут. Длинный поллинг вы запустите за полчаса. Вебхук потребует 40-60 минут, потому что нужен HTTPS-сертификат. Обработка ошибки 429 добавит еще 20 минут. Итого от двух до трех часов неспешной работы с проверками на каждом этапе.

Предварительная подготовка: инструменты и доступы

Прежде чем писать первую строку кода, соберем все необходимое. Так вы не будете прерываться посреди шага и искать, где взять пароль от прокси или как поставить библиотеку.

Необходимые инструменты и доступы

1. Аккаунт Telegram с привязанным номером. С него вы создадите бота через официального бота BotFather.
2. Доступ к прокси: адрес сервера, порт, логин и пароль. В личном кабинете mobileproxy.space эти данные показываются в карточке купленного прокси. Обычно доступны два порта: один для HTTP-подключения, другой для SOCKS5. Запишите оба.
3. Компьютер или сервер с установленным Python 3.10 или новее. Для вебхука понадобится сервер с публичным IP-адресом и доменом, на компьютере дома вебхук работать не будет.
4. Утилита curl. В Windows 10 и 11, macOS и Linux она уже встроена. Проверьте командой curl --version.
5. Текстовый редактор: VS Code, Notepad++ или любой другой, где удобно писать код.

Системные требования

Для поллинга требований почти нет: любая машина с доступом в интернет, включая ноутбук. Бот потребляет несколько десятков мегабайт памяти. Для вебхука нужен VPS с минимальной конфигурацией: 1 ядро, 1 ГБ оперативной памяти, Ubuntu 22.04 или 24.04. Обязателен домен, направленный на IP этого сервера, и открытый порт 443 в брандмауэре.

Что установить

1. Откройте терминал.
2. Проверьте Python командой python3 --version. На Windows команда может выглядеть как python --version.
3. Создайте папку проекта: mkdir tgbot-proxy, затем перейдите в нее cd tgbot-proxy.
4. Создайте виртуальное окружение: python3 -m venv venv. Активируйте его: на Linux и macOS source venv/bin/activate, на Windows venv\Scripts\activate.
5. Установите библиотеки: pip install requests[socks] flask. Пакет requests отвечает за запросы к Telegram Bot API, дополнение socks нужно для прокси по протоколу SOCKS5, а Flask примет вебхук.

Резервные копии и безопасность данных

Токен бота приравнивайте к паролю от банковского приложения. Тот, кто его получит, сможет писать от имени бота вашим клиентам. Заведите файл .env с токеном и данными прокси и никогда не отправляйте его в публичный репозиторий. Если бот уже работает и вы переносите его на прокси, сохраните текущую конфигурацию, сделайте выгрузку базы данных, если она есть, и запишите результат метода getWebhookInfo. Тогда откат займет две минуты.

Совет: Заведите отдельного тестового бота для экспериментов. Все шаги этого гайда сначала отработайте на нем, а на боевой бот переносите только проверенную конфигурацию. Так вы не сломаете общение с реальными клиентами.

Базовые понятия: как устроен Telegram Bot API

Разберем ключевые термины простыми словами. Без них дальнейшие шаги будут выглядеть как магия, а с ними станут логичными и предсказуемыми.

Telegram Bot API

Это обычный HTTP-интерфейс. Ваш код отправляет запрос на адрес вида https://api.telegram.org/bot<ТОКЕН>/<метод>, а сервер Telegram отвечает JSON-объектом. Например, метод getMe возвращает информацию о боте, а sendMessage отправляет текст в чат. Для работы не нужны специальные библиотеки, хватит curl или requests. Именно поэтому Telegram Bot API так легко пускать через прокси: это тот же трафик, что и у любого сайта по HTTPS.

Обновления (updates)

Каждое событие для бота, будь то сообщение, нажатие кнопки или добавление в группу, приходит в виде объекта update с уникальным номером update_id. Номера растут по порядку. Задача вашего кода получить эти объекты и обработать. Способов получения ровно два, и они взаимоисключающие.

Длинный поллинг (long polling)

Ваш бот сам спрашивает Telegram: есть ли для меня новые обновления? Делает он это методом getUpdates. Слово «длинный» означает, что сервер не отвечает мгновенно пустым списком, а держит соединение открытым до указанного таймаута, обычно 30-60 секунд, и отвечает сразу, как только появится событие. Это экономит запросы и дает почти мгновенную реакцию. Поллинг не требует публичного адреса, работает из-за роутера и через любой прокси. Идеален для старта и для ботов с небольшой нагрузкой.

Вебхук (webhook)

Обратный подход. Вы сообщаете Telegram адрес вашего сервера методом setWebhook, и Telegram сам присылает каждое обновление POST-запросом на этот адрес. Вам не нужно ничего опрашивать. Требования: публичный домен, HTTPS-сертификат и один из портов 443, 80, 88 или 8443. Вебхук лучше масштабируется и не тратит ресурсы на ожидание.

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

Ошибка 429 Too Many Requests

Telegram ограничивает частоту запросов. Ориентиры на 2026 год: не более одного сообщения в секунду в один чат, не более 20 сообщений в минуту в одну группу и порядка 30 сообщений в секунду суммарно на бота. При превышении сервер возвращает HTTP-статус 429 и в теле ответа поле parameters.retry_after с количеством секунд ожидания. Игнорировать его нельзя: повторные попытки без пауз увеличивают время блокировки.

Зачем вообще прокси для бота

Причины сугубо практические. Во-первых, фиксированный и предсказуемый исходящий IP: удобно, когда серверов много, а внешний адрес нужен один. Во-вторых, разделение трафика по проектам: у каждого клиента или каждой кампании свой канал. В-третьих, корпоративные политики, когда все внешние подключения обязаны идти через шлюз. Мобильные прокси здесь ценны стабильностью и возможностью управлять сменой IP по расписанию или по ссылке.

Шаг 1: Создаем бота и получаем токен

Цель этапа: получить токен доступа к Telegram Bot API и убедиться, что бот существует.

1. Откройте Telegram на телефоне или компьютере.
2. В строке поиска введите BotFather. Выберите бота с синей галочкой верификации, у поддельных ее нет.
3. Нажмите кнопку Start или отправьте команду /start. Вы увидите список доступных команд.
4. Отправьте команду /newbot.
5. BotFather попросит имя бота. Введите отображаемое имя, например Proxy Test Bot. Оно может содержать пробелы и русские буквы.
6. Далее попросят username. Он должен быть уникальным, латиницей и заканчиваться на bot, например proxy_test_2026_bot. Если имя занято, BotFather сообщит об этом, придумайте другое.
7. В ответ придет сообщение с поздравлением и строкой вида 123456789:AAExampleTokenLettersAndDigits. Это и есть токен. Скопируйте его целиком, включая цифры до двоеточия.
8. Создайте в папке проекта файл .env и запишите в него строку BOT_TOKEN=ваш_токен.

Внимание: Никогда не публикуйте токен в чатах, скриншотах и открытых репозиториях. Если токен утек, немедленно отправьте BotFather команду /revoke, выберите бота и получите новый токен. Старый перестанет работать сразу.

Первый запрос без прокси

Прежде чем усложнять схему, проверим, что токен рабочий, обычным запросом с вашей машины. Выполните в терминале, подставив свой токен:

curl https://api.telegram.org/bot123456789:AAExampleToken/getMe

Ожидаемый ответ: JSON, начинающийся с {"ok":true,"result":{"id":123456789,"is_bot":true,.... Внутри вы увидите username бота, который только что придумали.

Проверка: В ответе есть "ok":true и правильный username. Если вместо этого пришло "error_code":401, токен скопирован с ошибкой, проверьте, не потерялись ли символы по краям.

Возможные проблемы

• Username занят. Добавьте цифры или сокращение проекта, главное сохранить окончание bot.
• BotFather не отвечает. Убедитесь, что открыли бота с галочкой верификации, а не однофамильца.
• Ошибка 404 Not Found. В адресе пропущено слово bot перед токеном. Формат строго /bot<ТОКЕН>/метод.

Шаг 2: Подключаем прокси и проверяем доступ к API

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

Разбираемся с форматом адреса прокси

Прокси описывается одной строкой: протокол://логин:пароль@хост:порт. Возьмите данные из личного кабинета. Допустим, вам выдали хост proxy-host, порт HTTP 8080, порт SOCKS5 1080, логин user и пароль pass. Тогда строки будут такими:

• HTTP-прокси: http://user:pass@proxy-host:8080
• SOCKS5-прокси: socks5h://user:pass@proxy-host:1080

Обратите внимание на букву h в socks5h. Она означает, что доменное имя api.telegram.org будет разрешаться на стороне прокси, а не на вашей машине. Это правильный вариант для мобильных прокси: DNS-запросы и трафик идут одним маршрутом. Без буквы h при проблемах с локальным DNS запросы будут падать, хотя прокси исправен.

Если в пароле есть символы @, : или /, их нужно закодировать: @ превращается в %40, двоеточие в %3A, слеш в %2F. Иначе строка разберется неправильно.

Проверка через curl

1. Сначала узнайте, какой IP видят внешние сервисы через ваш прокси. Выполните: curl -x http://user:pass@proxy-host:8080 https://api.ipify.org. В ответ придет IP-адрес. Он должен отличаться от вашего домашнего или серверного адреса.
2. Теперь тот же запрос к Telegram Bot API: curl -x http://user:pass@proxy-host:8080 https://api.telegram.org/bot123456789:AAExampleToken/getMe.
3. Для SOCKS5 замените параметр: curl -x socks5h://user:pass@proxy-host:1080 https://api.telegram.org/bot123456789:AAExampleToken/getMe.
4. Замерьте время ответа: добавьте в конец команды -w " время: %{time_total}". Значение до 1-2 секунд для мобильного прокси нормально.

Проверка: Оба запроса вернули "ok":true, а IP из первой команды отличается от вашего собственного. Это означает, что маршрут через прокси работает и Telegram Bot API отвечает по нему.

Настраиваем прокси в Python

Создайте файл config.py со следующим содержимым, заменив значения на свои:

import os
TOKEN = os.getenv('BOT_TOKEN', '123456789:AAExampleTokenReplaceMe')
PROXY = os.getenv('BOT_PROXY', 'http://user:pass@proxy-host:8080')
PROXIES = {'http': PROXY, 'https': PROXY}
BASE = f'https://api.telegram.org/bot{TOKEN}'

Ключ https в словаре обязателен, потому что Telegram Bot API работает только по HTTPS. Частая ошибка новичков указать только http и удивляться, почему трафик идет напрямую.

Теперь тестовый скрипт check.py:

import requests
from config import PROXIES, BASE
ip = requests.get('https://api.ipify.org', proxies=PROXIES, timeout=15).text
print('Исходящий IP:', ip)
me = requests.get(f'{BASE}/getMe', proxies=PROXIES, timeout=15).json()
print('Бот:', me['result']['username'])

Запустите: python check.py. На экране появятся IP прокси и username бота.

Совет: Если не хотите менять код библиотеки, которую уже используете, задайте переменную окружения HTTPS_PROXY=http://user:pass@proxy-host:8080. Библиотека requests и большинство HTTP-клиентов подхватывают ее автоматически. Это удобный способ перевести существующего бота на прокси без правок.

Настройка в популярных фреймворках

• aiogram 3.x: создайте сессию AiohttpSession(proxy='http://user:pass@proxy-host:8080') и передайте ее при создании объекта Bot(token=TOKEN, session=session). Для SOCKS5 понадобится пакет aiohttp-socks.
• python-telegram-bot 21.x: используйте HTTPXRequest(proxy='http://user:pass@proxy-host:8080') и передайте его в ApplicationBuilder().token(TOKEN).request(request).
• Node.js: пакет https-proxy-agent или socks-proxy-agent создает агента, который передается в опции HTTP-клиента или в конструктор библиотеки бота.

Возможные проблемы

• 407 Proxy Authentication Required. Неверный логин или пароль либо не закодированы спецсимволы. Проверьте данные в кабинете.
• Connection refused. Порт указан неверно или перепутаны порты HTTP и SOCKS5. Попробуйте второй порт.
• Запрос идет напрямую. В словаре нет ключа https или переменная окружения задана в другом окне терминала.
• Ошибка SSL. Не отключайте проверку сертификата. Обновите пакет certifi командой pip install -U certifi и проверьте системное время.

Шаг 3: Запускаем длинный поллинг через прокси

Цель этапа: получить работающего бота, который через прокси забирает обновления методом getUpdates и отвечает на сообщения, не теряя и не дублируя их.

Как правильно строить цикл поллинга

Логика проста, но важны детали. Вы вызываете getUpdates с параметром offset, равным последнему обработанному update_id плюс один. Так Telegram понимает, что предыдущие обновления получены, и удаляет их со своей стороны. Если забыть про offset, одно и то же сообщение будет приходить снова и снова, а бот начнет отвечать несколько раз.

Параметр timeout задает, сколько секунд сервер держит соединение в ожидании событий. Здесь начинается специфика прокси. У любого прокси есть собственный таймаут неактивного соединения, у мобильных прокси он часто в районе 60-120 секунд. Если поллинговый таймаут больше, прокси оборвет соединение раньше, чем ответит Telegram, и вы получите ошибку вместо обновлений. Безопасное значение timeout=50 при таймауте HTTP-клиента 60 секунд. Таймаут клиента всегда должен быть больше таймаута поллинга, иначе клиент отвалится первым.

Пишем бота

1. Создайте файл polling.py.
2. Скопируйте код ниже.
3. Запустите его командой python polling.py.
4. Напишите боту любое сообщение в Telegram.

import time, requests
from config import PROXIES, BASE
offset = 0
print('Поллинг запущен через прокси')
while True:
try:
r = requests.get(f'{BASE}/getUpdates', params={'offset': offset, 'timeout': 50}, proxies=PROXIES, timeout=60)
data = r.json()
except requests.RequestException as e:
print('Сетевая ошибка:', e)
time.sleep(3)
continue
if not data.get('ok'):
print('Ошибка API:', data)
time.sleep(3)
continue
for upd in data['result']:
offset = upd['update_id'] + 1
msg = upd.get('message')
if msg and 'text' in msg:
requests.post(f'{BASE}/sendMessage', json={'chat_id': msg['chat']['id'], 'text': 'Принял: ' + msg['text']}, proxies=PROXIES, timeout=15)

Разберем, что здесь происходит. Внешний цикл никогда не завершается сам. Блок try перехватывает сетевые ошибки: обрыв прокси, таймаут, смену IP. При ошибке скрипт ждет три секунды и пробует снова, а не падает. Проверка data.get('ok') ловит ошибки уровня API. Внутренний цикл обрабатывает каждое обновление и сразу сдвигает offset.

Проверка: В консоли появилась строка о запуске, а после отправки сообщения бот ответил «Принял: ваш текст». Отправьте три сообщения подряд, бот должен ответить ровно на каждое по одному разу. Остановите скрипт клавишами Ctrl+C, отправьте сообщение, запустите снова: бот ответит на пропущенное сообщение, потому что Telegram хранит необработанные обновления до 24 часов.

Особенности мобильных прокси при поллинге

Мобильные прокси умеют менять IP-адрес: по таймеру или по специальной ссылке из кабинета. В момент смены IP открытое соединение поллинга разрывается. Это не ошибка вашего кода, это нормальное поведение сети. Наш цикл уже готов к этому: перехватит исключение, подождет и продолжит с того же offset. Ни одно обновление не потеряется.

Тем не менее частая ротация создает лишний шум в логах и микрозадержки. Рекомендация: для бота на поллинге выставьте в кабинете интервал ротации от 10 минут и больше либо отключите автоматическую смену и меняйте IP по ссылке только тогда, когда это действительно нужно. Бот не парсер, ему не требуется свежий адрес каждую минуту.

Совет: Добавьте в лог время и update_id каждого обновления. Когда через неделю кто-то скажет, что бот не ответил, вы за минуту найдете, дошло ли сообщение до вашего кода или проблема была на стороне сети.

Возможные проблемы

• Ошибка 409 Conflict. Самая частая. У бота установлен вебхук, а поллинг с вебхуком одновременно работать не могут. Выполните curl -x ваш_прокси https://api.telegram.org/botТОКЕН/deleteWebhook и перезапустите скрипт. Вторая причина: запущены две копии скрипта, закройте лишнюю.
• Бот отвечает на каждое сообщение дважды. Offset не сдвигается или запущены две копии бота.
• Постоянные Read timed out. Таймаут поллинга больше таймаута прокси. Уменьшите timeout до 30-40 секунд.
• Задержка ответа 5-10 секунд. Проверьте время ответа прокси через curl. Если медленный сам канал, смените точку выхода или тариф.

Шаг 4: Настраиваем вебхук с HTTPS и секретным токеном

Цель этапа: Telegram сам присылает обновления на ваш сервер, а бот отвечает через прокси. Этот шаг требует VPS с доменом, поэтому если у вас пока только поллинг и он вас устраивает, можете перейти к шагу 5 и вернуться сюда позже.

Подготовка сервера и домена

1. Арендуйте VPS с Ubuntu. Запишите его публичный IP.
2. В панели управления доменом создайте A-запись, например bot.example.com, указывающую на IP сервера. Дождитесь обновления DNS, обычно 5-30 минут. Проверьте командой nslookup bot.example.com.
3. Подключитесь к серверу по SSH и обновите пакеты: sudo apt update.
4. Установите nginx и certbot: sudo apt install nginx certbot python3-certbot-nginx.
5. Откройте порты 80 и 443: sudo ufw allow 80, sudo ufw allow 443.
6. Получите бесплатный сертификат: sudo certbot --nginx -d bot.example.com. Следуйте подсказкам, введите email, согласитесь с условиями. Через минуту сертификат будет выпущен.

Telegram принимает вебхуки только по HTTPS с валидным сертификатом от доверенного центра. Сертификат от certbot этому требованию соответствует. Самоподписанный сертификат тоже возможен, но тогда его публичную часть придется загрузить параметром certificate в setWebhook, и это добавит хлопот. Для начинающих certbot проще.

Настраиваем nginx как входную точку

Nginx будет принимать HTTPS-запросы от Telegram и передавать их вашему приложению на Flask, которое слушает локальный порт 8080. Откройте конфиг сайта, созданный certbot, командой sudo nano /etc/nginx/sites-available/default и добавьте внутрь блока server с портом 443 такой location:

location /tg/webhook {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_read_timeout 30s;
}

Сохраните файл, проверьте синтаксис sudo nginx -t и перезагрузите sudo systemctl reload nginx.

Совет: Сделайте путь вебхука неочевидным, например /tg/webhook/k8s7d2f. Это не замена секретному токену, а дополнительный слой: случайные сканеры не найдут вашу точку входа.

Пишем обработчик вебхука

Создайте на сервере файл webhook.py. Он принимает POST от Telegram, проверяет секретный заголовок и отвечает пользователю через прокси. Функцию call мы напишем в следующем шаге, пока используйте обычный requests.post с proxies.

import requests
from flask import Flask, request, abort
from config import PROXIES, BASE
app = Flask(__name__)
SECRET = 'MySecret123'
@app.post('/tg/webhook')
def webhook():
if request.headers.get('X-Telegram-Bot-Api-Secret-Token') != SECRET:
abort(403)
update = request.get_json(silent=True) or {}
msg = update.get('message')
if msg and 'text' in msg:
requests.post(f'{BASE}/sendMessage', json={'chat_id': msg['chat']['id'], 'text': 'Получил через вебхук'}, proxies=PROXIES, timeout=15)
return 'ok', 200
if __name__ == '__main__':
app.run(host='127.0.0.1', port=8080)

Ключевой момент: заголовок X-Telegram-Bot-Api-Secret-Token. Telegram добавляет его к каждому запросу, если вы указали secret_token при установке вебхука. Любой запрос без правильного значения отклоняется с кодом 403. Так никто посторонний не сможет подсунуть боту поддельные сообщения.

Запустите приложение: python webhook.py. Для постоянной работы позже оформите его как systemd-сервис, но для проверки хватит и прямого запуска.

Регистрируем вебхук через прокси

Сам вызов setWebhook тоже идет через прокси, ведь это исходящий запрос к Telegram Bot API. Выполните на любой машине с доступом к прокси:

curl -x http://user:pass@proxy-host:8080 -F "url=https://bot.example.com/tg/webhook" -F "secret_token=MySecret123" -F "max_connections=40" -F "drop_pending_updates=true" https://api.telegram.org/bot123456789:AAExampleToken/setWebhook

Разберем параметры. url — адрес вашего обработчика. secret_token — строка от 1 до 256 символов из латинских букв, цифр, дефиса и подчеркивания; она должна совпадать с SECRET в коде. max_connections — сколько одновременных запросов Telegram может открыть к вам, от 1 до 100, по умолчанию 40. drop_pending_updates — сбросить накопившиеся обновления, чтобы бот не выдал шквал старых ответов в момент переключения.

Ожидаемый ответ: {"ok":true,"result":true,"description":"Webhook was set"}.

Диагностика через getWebhookInfo

Это главный инструмент отладки вебхуков. Выполните:

curl -x http://user:pass@proxy-host:8080 https://api.telegram.org/bot123456789:AAExampleToken/getWebhookInfo

В ответе смотрите на поля: url должен совпадать с вашим, pending_update_count показывает очередь необработанных обновлений, last_error_date и last_error_message появляются, если Telegram не смог доставить обновление. Пустое поле ошибки после отправки тестового сообщения означает полный успех.

Проверка: Напишите боту. Он ответил «Получил через вебхук». В getWebhookInfo нет last_error_message, а pending_update_count равен нулю. В логах Flask видна строка с POST /tg/webhook и кодом 200.

Внимание: Обработчик вебхука должен отвечать быстро, в пределах нескольких секунд. Если ваш код долго думает, например делает тяжелый запрос к базе или к внешнему сервису через медленный прокси, Telegram посчитает доставку неудачной и повторит ее. Тяжелую работу выносите в фоновую задачу, а вебхуку возвращайте 200 сразу.

Возможные проблемы

• last_error_message: SSL error. Сертификат не валиден, истек или выдан на другой домен. Проверьте sudo certbot certificates.
• Connection timed out. Порт 443 закрыт в брандмауэре или у хостера. Проверьте sudo ufw status и настройки в панели VPS.
• Wrong response from the webhook: 403. Секретный токен в коде и в setWebhook не совпадает. Проверьте регистр букв.
• Wrong response from the webhook: 502. Flask не запущен или слушает другой порт. Проверьте ss -tlnp | grep 8080.
• Bad webhook: port not allowed. Используйте только 443, 80, 88 или 8443.

Шаг 5: Обрабатываем ошибку 429 и делаем запросы устойчивыми

Цель этапа: написать одну функцию для всех вызовов Telegram Bot API, которая сама выдерживает паузу при 429, повторяет запрос при сбоях сети и прокси и никогда не роняет бота.

Почему 429 нельзя игнорировать

Когда вы отправляете рассылку по тысяче пользователей, лимит в 30 сообщений в секунду достигается мгновенно. Telegram отвечает 429 и указывает retry_after. Если продолжать долбить сервер, сообщения не уйдут, а время ожидания в следующих ответах вырастет. При работе через прокси есть нюанс: лимиты Telegram привязаны к боту, а не к IP. Смена IP через ротацию не поможет обойти ограничение и не должна использоваться для этого. Единственный правильный путь — уважать retry_after и контролировать скорость отправки.

Пишем универсальную обертку

Добавьте в файл config.py или в отдельный api.py следующую функцию:

import time, requests
from config import PROXIES, BASE
def call(method, payload, retries=6):
for attempt in range(retries):
try:
r = requests.post(f'{BASE}/{method}', json=payload, proxies=PROXIES, timeout=15)
except requests.RequestException as e:
print('Сеть или прокси:', e)
time.sleep(min(2 ** attempt, 30))
continue
if r.status_code == 429:
wait = r.json().get('parameters', {}).get('retry_after', 1)
print('429 Too Many Requests, ждем', wait, 'сек')
time.sleep(wait + 0.5)
continue
if 500 <= r.status_code < 600:
print('Ошибка сервера Telegram', r.status_code)
time.sleep(min(2 ** attempt, 30))
continue
data = r.json()
if not data.get('ok'):
print('Ошибка API:', data.get('description'))
return data
raise RuntimeError('Telegram Bot API: исчерпаны попытки для ' + method)

Что делает эта функция. При сетевой ошибке ждет по экспоненте: 1, 2, 4, 8 секунд, но не более 30. Так бот переживает смену IP на прокси или короткий сбой канала. При 429 читает retry_after, добавляет полсекунды запаса и повторяет. При ошибках 5xx на стороне Telegram тоже повторяет с паузой. При ошибках 400 или 403, например если пользователь заблокировал бота, повтор бесполезен, поэтому функция возвращает ответ как есть, и вы решаете, что делать дальше.

Ограничиваем скорость заранее

Лучше не доводить до 429 вовсе. Для рассылок добавьте паузу между сообщениями. Простейший вариант: time.sleep(0.05) после каждой отправки дает 20 сообщений в секунду, что ниже общего лимита. Для одного чата держите паузу не меньше секунды. Для групп не чаще 20 сообщений в минуту.

def broadcast(chat_ids, text):
sent, failed = 0, 0
for cid in chat_ids:
res = call('sendMessage', {'chat_id': cid, 'text': text})
if res.get('ok'):
sent += 1
else:
failed += 1
time.sleep(0.05)
print('Отправлено:', sent, 'Ошибок:', failed)

Совет: Сохраняйте ответы с ошибкой 403 Forbidden: bot was blocked by the user. Удаляйте таких пользователей из базы рассылки. Это снизит нагрузку и защитит от лишних лимитов, ведь неудачные запросы тоже считаются.

Тестируем обработку 429

1. Создайте тестовую группу и добавьте туда бота.
2. Запустите цикл из 40 вызовов call('sendMessage', {...}) в этот чат без пауз.
3. Наблюдайте в консоли: после нескольких быстрых отправок появится строка о 429 и времени ожидания.
4. Убедитесь, что после паузы отправка продолжилась и все 40 сообщений дошли.

Проверка: Все сообщения доставлены, бот не упал с исключением, в логе видны паузы retry_after. Замените requests.post в polling.py и webhook.py на функцию call, чтобы вся работа с Telegram Bot API шла через один защищенный канал.

Возможные проблемы

• retry_after огромный, сотни секунд. Вы долго игнорировали лимит. Остановите отправку полностью, подождите указанное время и снизьте темп.
• 429 приходит уже на первых сообщениях. Другой процесс использует тот же токен. Проверьте, не запущена ли старая версия бота.
• Ответ не JSON при 429. Некоторые прокси возвращают собственную HTML-страницу об ошибке. Оберните r.json() в try и при неудаче ждите фиксированные 5 секунд.

Шаг 6: Продвинутые настройки для нагруженных проектов

Цель этапа: подготовить бота к росту: несколько ботов через несколько прокси, очередь отправки, локальный сервер Bot API и грамотная ротация. Начинающие могут пропустить раздел и вернуться, когда пользователей станет больше тысячи.

Несколько ботов через разные прокси

Маркетологи часто ведут десяток ботов для разных проектов с одного сервера. Правильная архитектура: для каждого бота свой словарь proxies и своя сессия requests.Session(). Сессия переиспользует TCP-соединения, что снижает нагрузку на прокси и ускоряет запросы в 2-3 раза. Храните конфигурацию в виде списка: токен, адрес прокси, режим получения обновлений. Один процесс на бота проще отлаживать, чем один процесс на все.

Очередь отправки вместо прямых вызовов

Для рассылок от 10 тысяч пользователей прямые вызовы из основного кода перестают работать. Заведите очередь: Redis или хотя бы таблицу в базе с полями chat_id, text, status, attempts. Отдельный воркер забирает задания и вызывает функцию call с контролем скорости. При 429 воркер спит, а не блокирует прием вебхуков. Так бот продолжает отвечать на команды пользователей, пока рассылка идет в фоне. На 2026 год Telegram Bot API позволяет платным ботам через параметр allow_paid_broadcast повышать лимит до 1000 сообщений в секунду, но за это списываются Stars, поэтому для большинства проектов очередь с 20-25 сообщениями в секунду остается оптимальным вариантом.

Локальный Bot API Server

Telegram публикует исходники сервера Bot API, который можно запустить у себя. Ваш код тогда обращается не к api.telegram.org, а к localhost, а сам локальный сервер общается с Telegram. Плюсы: загрузка файлов до 2 ГБ вместо 50 МБ, вебхуки на любой порт и без HTTPS внутри вашей сети, снятие ряда лимитов. Минус: прокси придется настраивать на уровне самого локального сервера, а не в коде бота. Вариант для команд с DevOps-компетенцией, для старта избыточен.

Ротация IP и вебхуки

При вебхуках ротация IP на прокси почти незаметна: каждый вызов sendMessage короткий, и разрыв соединения в момент смены затронет максимум один запрос, который обертка call повторит. Поэтому для вебхуков допустима более частая ротация, чем для поллинга. Тем не менее смысла в частой смене нет: Telegram Bot API не ограничивает запросы по IP, а лимиты завязаны на токен. Ставьте ротацию из соображений вашей инфраструктуры, а не ради API.

Мониторинг здоровья без отдельной системы

Минимальный набор, который стоит завести сразу: раз в минуту вызывайте getWebhookInfo и пишите в лог pending_update_count и last_error_message. Если очередь растет три замера подряд, ваш обработчик не справляется. Для поллинга записывайте время последнего успешного getUpdates: если прошло больше двух минут, соединение зависло, перезапустите процесс. Этого достаточно, чтобы узнавать о проблемах раньше клиентов.

Совет: Логируйте не только ошибки, но и время каждого запроса к Telegram Bot API через прокси. Медленный рост среднего времени ответа с 0,3 до 2 секунд предупредит о деградации канала за дни до того, как бот начнет терять сообщения.

Проверка результата: чек-лист готового решения

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

Чек-лист

• Команда curl с параметром -x через прокси возвращает "ok":true на метод getMe.
• Скрипт check.py показывает IP прокси, а не ваш собственный.
• Поллинг отвечает на сообщение один раз, без дублей.
• После остановки и перезапуска поллинга пропущенные сообщения обрабатываются.
• При принудительной смене IP на прокси поллинг восстанавливается сам за 3-5 секунд.
• Вебхук: getWebhookInfo показывает ваш url, нулевой pending_update_count и пустое last_error_message.
• Запрос к вебхуку без секретного заголовка получает 403.
• Быстрая отправка 40 сообщений в один чат проходит без падения, в логе видны паузы retry_after.
• Токен и данные прокси лежат в .env, а не в коде.

Как протестировать целиком

1. Запустите бота в выбранном режиме.
2. Напишите ему с трех разных аккаунтов по два сообщения.
3. Убедитесь в шести ответах, по одному на каждое сообщение.
4. Нажмите в кабинете прокси ссылку смены IP и сразу отправьте еще сообщение.
5. Бот должен ответить в течение 10 секунд.
6. Запустите тест на 429 из шага 5.
7. Проверьте логи: нет необработанных исключений и трассировок.

Показатели успеха

Время ответа бота на сообщение до 2 секунд. Доля неуспешных запросов к Telegram Bot API после всех повторов ниже 0,1 процента. Ни одного дубля за сутки работы. pending_update_count в getWebhookInfo не превышает десяти в пиковые часы. Если показатели соответствуют, поздравляем: вы собрали надежную схему, которой хватит на долгие месяцы.

Типичные ошибки и их решения

Ошибка 409 Conflict при getUpdates

Причина: для бота установлен вебхук либо запущено два экземпляра поллинга. Решение: вызвать deleteWebhook через прокси, убедиться, что работает только один процесс. Проверьте команду ps aux | grep polling.

Бот отвечает дважды на каждое сообщение

Причина: offset не увеличивается или запущено две копии бота на разных серверах с одним токеном. Решение: проверьте строку offset = update_id + 1, остановите лишние копии. Для вебхука убедитесь, что nginx не дублирует запросы двум бэкендам.

Ошибка 407 Proxy Authentication Required

Причина: неверные учетные данные прокси или незакодированные спецсимволы в пароле. Решение: перепроверьте логин и пароль в кабинете, закодируйте @, : и / в пароле, попробуйте авторизацию по IP, если она доступна в вашем тарифе.

Read timed out каждые 50-60 секунд

Причина: таймаут поллинга больше или равен таймауту простоя на прокси. Решение: снизьте timeout в getUpdates до 30-40 секунд, а таймаут клиента держите на 10 секунд больше.

Вебхук установлен, но обновления не приходят

Причина: порт закрыт, сертификат недействителен или обработчик отвечает не 200. Решение: смотрите last_error_message в getWebhookInfo, это точный диагноз. Проверьте curl -I https://bot.example.com/tg/webhook с другого компьютера.

Wrong response from the webhook: 403 Forbidden

Причина: секретный токен в коде отличается от переданного в setWebhook. Решение: переустановите вебхук с тем же значением, что в коде. Помните, что setWebhook с новыми параметрами полностью заменяет предыдущие.

Постоянные 429 при небольшой нагрузке

Причина: бот отправляет в один чат чаще раза в секунду, например несколько сообщений подряд в ответ на одну команду. Решение: объединяйте ответы в одно сообщение, используйте editMessageText вместо новых сообщений для прогресса, добавьте паузу между отправками в один chat_id.

Трафик идет напрямую, минуя прокси

Причина: в словаре proxies нет ключа https, переменная окружения не видна процессу, фреймворк не подхватил настройку. Решение: проверьте исходящий IP запросом к api.ipify.org внутри того же кода, которым отправляете сообщения. Не доверяйте предположениям, проверяйте фактически.

SSL: CERTIFICATE_VERIFY_FAILED при запросах через прокси

Причина: устаревший набор корневых сертификатов или неверное системное время. Решение: обновите certifi, синхронизируйте время. Никогда не отключайте проверку сертификатов параметром verify=False: это открывает возможность подмены трафика с токеном.

FAQ: частые вопросы по настройке

Что выбрать для начала: поллинг или вебхук?

Поллинг. Он работает откуда угодно, не требует домена и сертификата, а переключиться на вебхук можно позже за час. Вебхук имеет смысл, когда бот обслуживает тысячи пользователей или работает на сервере, где уже есть HTTPS.

Можно ли использовать один прокси для нескольких ботов?

Да. Лимиты Telegram Bot API привязаны к токену бота, а не к IP. Десять ботов через один прокси не мешают друг другу с точки зрения API. Единственное ограничение — пропускная способность самого прокси, для текстовых ботов ее хватает с большим запасом.

Обязательно ли пускать через прокси и вебхук, и ответы?

Входящие запросы вебхука приходят напрямую на ваш сервер, через прокси их пустить невозможно по определению. Через прокси идут только исходящие вызовы: sendMessage, setWebhook, getFile и остальные методы. Это нормальная и единственно возможная схема.

Как понять, что запросы действительно идут через прокси?

Внутри того же кода запросите https://api.ipify.org с теми же настройками proxies и сравните с вашим реальным IP. Дополнительно можно посмотреть статистику трафика в кабинете прокси: счетчик должен расти при работе бота.

Что делать при смене IP на прокси во время работы бота?

Ничего, если вы использовали код из этого гайда. Поллинг перехватит разрыв соединения и продолжит с сохраненного offset. Функция call повторит неудавшийся запрос. Единственная рекомендация: не ставить ротацию чаще чем раз в несколько минут для режима поллинга.

SOCKS5 или HTTP-прокси для Telegram Bot API?

Разницы для бота почти нет, оба работают. HTTP-прокси проще настраивается и поддерживается всеми клиентами без дополнительных пакетов. SOCKS5 удобнее, когда вы хотите гарантированно разрешать DNS на стороне прокси через схему socks5h. Выбирайте то, что уже используете в других проектах.

Сколько сообщений можно отправлять, чтобы не получить 429?

Держитесь ориентиров: до 1 сообщения в секунду в личный чат, до 20 в минуту в группу, до 25-30 в секунду суммарно. Для массовых рассылок закладывайте 20 сообщений в секунду и обязательно обрабатывайте retry_after, потому что лимиты могут временно снижаться при высокой нагрузке на Telegram.

Как безопасно перевести уже работающего бота на прокси?

Сначала проверьте прокси через curl на getMe. Затем добавьте переменную HTTPS_PROXY или настройте proxies в коде, запустите бота на тестовом токене. Только после успешных проверок переключите боевой токен. Держите старую конфигурацию под рукой для отката.

Как откатить вебхук и вернуться к поллингу?

Один вызов deleteWebhook через прокси. Если хотите сохранить накопившиеся обновления для поллинга, не передавайте drop_pending_updates. После этого запускайте polling.py, и бот подхватит очередь.

Можно ли задать несколько URL вебхука для одного бота?

Нет, у бота ровно один вебхук. Если нужно распределять нагрузку, ставьте за единственным URL балансировщик nginx, который раскидывает запросы по нескольким экземплярам приложения. Для Telegram это выглядит как одна точка входа.

Заключение

Давайте подведем итог проделанной работы. Вы создали бота и получили токен, научились проверять прокси через curl и Python, убедились, что трафик к Telegram Bot API идет по нужному маршруту. Вы собрали устойчивый цикл длинного поллинга, который переживает смену IP и не дублирует сообщения. Вы подняли вебхук с настоящим HTTPS-сертификатом и защитили его секретным токеном. И самое ценное: вы написали одну функцию, которая уважает retry_after при 429, повторяет запросы при сбоях сети и превращает капризный канал в надежный.

Что делать дальше. Оформите бота как systemd-сервис, чтобы он поднимался после перезагрузки сервера. Вынесите токены и адреса прокси в переменные окружения на боевой машине. Добавьте простой лог времени ответов и раз в неделю просматривайте его. Если пользователей становится много, переходите к очереди отправки из продвинутого раздела.

Куда развиваться. Изучите методы Telegram Bot API для инлайн-кнопок, платежей и мини-приложений, они открывают ботам совершенно новые сценарии для маркетинга и продаж. Освойте асинхронные фреймворки aiogram или python-telegram-bot, они возьмут на себя рутину поллинга и повторов, а вы уже понимаете, что происходит у них под капотом. И главное: не бойтесь экспериментировать на тестовом боте. Каждая ошибка 429 или 409, которую вы поймали и починили сами, делает вас сильнее любого готового шаблона. У вас все получится.