1 Прокси в самом приложении Telegram

Через прокси можно пустить не только бота. У клиента Telegram на компьютере и на телефоне есть своя настройка прокси, отдельная от системной. Поддерживаются SOCKS5 и MTProto, в свежих сборках для компьютера есть и HTTP. Для плана GeekProxy выбирайте SOCKS5 и логин с паролем из кабинета. HTTP на компьютере настраивается так же.

Компьютер (Windows, macOS, Linux): Settings, Advanced, Connection type, Use custom proxy, Add proxy. Выберите SOCKS5, в Hostname впишите хост, в Port порт, в блоке Credentials логин и пароль. Сохраните. Прокси действует только для этого Telegram, остальные программы ходят своим путём.

Android: Settings, Data and Storage, Proxy Settings, Add Proxy, SOCKS5. iPhone: Settings, Data and Storage, Proxy, Add Proxy, SOCKS5. Те же четыре поля: сервер, порт, логин, пароль. У рабочего прокси в списке появляется зелёный статус connected.

Самый быстрый путь на любом устройстве это ссылка. Формат описан в документации Telegram: https://t.me/socks?server=IP&port=PORT&user=LOGIN&pass=PASSWORD. Откройте её на устройстве, и Telegram предложит добавить прокси с уже заполненными полями. Вариант MTProto (t.me/proxy?…&secret=) требует сервер MTProxy, GeekProxy его не предоставляет.

В окне есть предупреждение, что прокси может показывать спонсорский канал. Это особенность MTProto-прокси. SOCKS5 или HTTP со своим логином ничего в список чатов не добавляет.

Для личного аккаунта естественный выбор ISP: один статический адрес на месяцы, под залогиненной сессией ничего не ротируется. Для многих аккаунтов в отдельных клиентах берите Residential Turbo со sticky-сессией, по сессии на аккаунт.

2 Перед началом

Каждый вызов Bot API это HTTPS-запрос на https://api.telegram.org/bot<token>/METHOD. Telegram требует именно HTTPS. Значит, у прокси одна задача: пронести CONNECT-туннель или SOCKS5-соединение до api.telegram.org на порт 443. Всё остальное Telegram не волнует.

Сразу про главную путаницу. MTProto-прокси это другой механизм: собственный транспорт Telegram, 16-байтный секрет, ссылки вида tg://proxy?server=...&port=...&secret=.... Работают с ними только MTProto-клиенты, то есть приложения Telegram и Telethon. python-telegram-bot, aiogram, grammY и Telegraf с ними не умеют: они говорят с Bot API обычным HTTPS. GeekProxy продаёт HTTP- и SOCKS5-прокси, а не MTProto. Ровно их эти библиотеки и принимают.

• Через прокси идут только запросы самой библиотеки. Остальные процессы на машине не затронуты
• В режиме вебхука Telegram сам подключается к вашему серверу. Прокси в приёме апдейтов не участвует, он несёт только ваши исходящие вызовы

Что понадобится

• Активный план GeekProxy (датацентр, ISP или резидентские)
• Данные прокси из кабинета: хост, порт, логин, пароль
• Python 3 для python-telegram-bot, aiogram и Telethon; Node.js для grammY и Telegraf
• Токен бота от @BotFather. Он бесплатный

3 Где взять данные прокси

1. Войдите в кабинет GeekProxy
2. Откройте план. У планов с оплатой за IP (датацентр, ISP) список адресов, порты, логин и пароль лежат прямо на карточке, а кнопка Export отдаёт весь список текстом
3. У резидентских и мобильных планов нажмите Options. Панель Proxy Configuration соберёт строку логина с вашей страной, городом и настройками сессии. Готовую строку копируйте из Proxy List

Бот, который месяцами живёт на сервере, может забирать прокси из API GeekProxy при старте, а не держать строку в коде. Вызовы разобраны в гайде по автоматизации.

4 python-telegram-bot

Версия 22 работает поверх httpx через класс HTTPXRequest, и прокси там обычный параметр proxy: строка, httpx.Proxy или httpx.URL. Напрямую класс трогают редко. ApplicationBuilder выносит то же самое в два метода.

• .proxy(url) задаёт прокси для всех вызовов методов Bot: sendMessage, getFile, всё подряд
• .get_updates_proxy(url) касается только getUpdates, то есть long polling

Официальная вики пишет, что задавать оба не обязательно. На практике нужны оба, иначе опрос идёт напрямую, а ответы через GeekProxy. Бот, который наполовину за прокси, отлаживать то ещё удовольствие.

from telegram.ext import ApplicationBuilder

# часть "LOGIN:PASSWORD@" не нужна, если план на белом списке IP
PROXY = "http://LOGIN:PASSWORD@IP:PORT"

app = (
    ApplicationBuilder()
    .token("TOKEN")
    .proxy(PROXY)
    .get_updates_proxy(PROXY)
    .build()
)
# дальше хендлеры и запуск polling как обычно

SOCKS5 и переменные окружения

Для SOCKS5 ставим extra и меняем схему. Команда из документации pip install python-telegram-bot[socks], строка прокси становится socks5://LOGIN:PASSWORD@IP:PORT. Если в коде ничего не задано, PTB берёт прокси из переменных HTTP_PROXY, HTTPS_PROXY и ALL_PROXY. Есть нюанс. В документации прямо сказано: SOCKS5 через переменные окружения задать нельзя. Либо SOCKS в коде, либо HTTP.

Ещё одно значение по умолчанию: HTTPXRequest ждёт connect_timeout=5.0 и read_timeout=5.0 секунд. Резидентский выход в плохой день может в это не уложиться.

5 aiogram 3 и Telethon

aiogram 3 вешает прокси на объект сессии: AiohttpSession(proxy=...), которая передаётся в Bot(token, session=session). Документация просит поставить aiohttp-socks для коннектора с прокси и перечисляет протоколы: http в режиме туннеля, socks4 и socks4a, socks5. Аргумент proxy принимает три формы.

• Строку URL с логином внутри: "http://LOGIN:PASSWORD@IP:PORT"
• Кортеж из URL и aiohttp.BasicAuth, удобно при паролях со спецсимволами
• Список из того и другого, получается цепочка прокси

# pip install aiohttp-socks
from aiogram import Bot
from aiogram.client.session.aiohttp import AiohttpSession
from aiohttp import BasicAuth

auth = BasicAuth(login="LOGIN", password="PASSWORD")
session = AiohttpSession(proxy=("http://IP:PORT", auth))
bot = Bot(token="TOKEN", session=session)

Если передать и URL с логином, и объект BasicAuth, документация однозначна: aiogram возьмёт BasicAuth.

Telethon

Telethon не библиотека Bot API. Он говорит с дата-центрами Telegram по MTProto, поэтому годится и для юзерботов, и для входа по токену бота. Прокси при этом задаётся как обычный SOCKS5 или HTTP. Сначала поставьте python-socks[asyncio], иначе Telethon выдаст предупреждение и подключится без прокси. Потом передайте словарь.

# pip install "python-socks[asyncio]"
from telethon import TelegramClient

proxy = {
    'proxy_type': 'socks5',      # (обязательно) протокол
    'addr': 'IP',     # (обязательно) IP прокси
    'port': PORT,               # (обязательно) порт прокси
    'username': 'LOGIN',    # (опционально) логин, если прокси с авторизацией
    'password': 'PASSWORD',    # (опционально) пароль
    'rdns': True                 # (опционально) резолвить на прокси, по умолчанию да
}

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

rdns по умолчанию включает удалённый резолв, то есть DNS отрабатывает на стороне прокси. Хорошее значение, не трогайте. На странице Telethon для proxy_type расписан только 'socks5'; python-socks умеет и HTTP CONNECT, точное значение есть в его README. И да, это единственная библиотека из списка, которая умеет MTProto-прокси: кортеж из хоста, порта и секрета плюс явный класс в connection=. Со словарём выше это никак не связано.

6 grammY и Telegraf

Обе Node.js-библиотеки устроены одинаково: HTTP-клиенту отдаётся агент, а про прокси знает агент. У grammY есть официальная страница на эту тему. У Telegraf есть типизированная опция и ни одного примера, так что его сниппет ниже собран по типам опций.

grammY

Документированный путь: socks-proxy-agent в поле client.baseFetchConfig.agent. На странице grammY агент собирают из объекта с hostname и port; README самого агента принимает URL с логином внутри, и с авторизацией нужен именно он. Символ @ в логине кодируйте как %40.

import { Bot } from "grammy";
import { SocksProxyAgent } from "socks-proxy-agent";

const agent = new SocksProxyAgent(
  "socks5h://LOGIN:PASSWORD@IP:PORT",
);

const bot = new Bot("TOKEN", {
  client: {
    baseFetchConfig: {
      agent,
      compress: true,
    },
  },
});

Два замечания с официальной страницы. Задайте агенту опцию timeout: собственный таймаут запроса у grammY 500 секунд, и мёртвый сокет он закрыть не может, а агент может. И оставьте compress: true, это часть конфига fetch по умолчанию, который вы переопределяете. Про схему: socks5h:// и просто socks:// отдают резолв имён прокси, socks5:// резолвит у вас на машине. Для HTTP-прокси в то же поле agent кладётся HttpsProxyAgent, собранный как в примере для Telegraf ниже.

Telegraf

Конструктор Telegraf принимает { telegram: { agent } }, агент для общения с Bot API. Создавайте его один раз при старте. Агент по умолчанию с keep-alive, и комментарий в исходниках предупреждает, что новый агент на каждый запрос, скорее всего, это ломает.

const { Telegraf } = require('telegraf');
const { HttpsProxyAgent } = require('https-proxy-agent');   // или SocksProxyAgent

const agent = new HttpsProxyAgent('http://LOGIN:PASSWORD@IP:PORT');
const bot = new Telegraf(process.env.BOT_TOKEN, { telegram: { agent } });

7 Проверка работы

Сначала проверьте прокси, потом вините библиотеку. Выполните curl -x http://LOGIN:PASSWORD@IP:PORT https://ipinfo.io/json с той же машины. Эндпоинт публичный и возвращает IP, который видит. Это должен быть прокси, а не ваш сервер.

Потом запустите бота с логированием на уровне INFO и напишите ему. В логе должен завершиться запрос getUpdates, а хендлер сработать. Неверный порт проявится за секунды ошибкой соединения на первом же вызове. В curl прокси работает, а бот падает? Ошибка в настройке библиотеки. Падает и то и другое? Логин, пароль или план.

8 Какой продукт GeekProxy подходит

Боту нужен один стабильный исходящий туннель, круглые сутки, с копеечным трафиком и без ротации. Это план с оплатой за IP: датацентр IPv4 самый дешёвый способ его получить, а у планов за IP нет счётчика трафика, так что long polling может крутиться вечно. Статический ISP берут, когда юзербот на Telethon должен показывать владельцу аккаунта вход с домашнего на вид адреса. Residential Turbo и Residential Flex тарифицируются по гигабайтам и по умолчанию ротируются. Sticky-сессия работает: Turbo держит один IP до 1440 минут, Flex до 120. Но вызову Bot API домашний IP ничего не даёт, а открытое соединение опроса тихо тратит трафик. Flex работает только по TCP, Bot API этого не замечает. Мобильные для трафика Bot API тоже ничего не добавляют.

9 Частые проблемы

Бот отвечает, но не получает сообщения

python-telegram-bot с заданным .proxy() и без .get_updates_proxy(). Ответы уходят через GeekProxy, опрос идёт напрямую, и если прямой путь закрыт, ни один апдейт не доходит. Задайте оба.

TypeError: unexpected keyword argument 'proxy_url'

У вас python-telegram-bot 22, а сниппет старше. proxy_url убрали в 22.0. Переименуйте в proxy.

HTTPS_PROXY=socks5://... игнорируется

Так задумано в python-telegram-bot: SOCKS5 через переменные окружения не настраивается. Передайте SOCKS-URL в .proxy() в коде или поменяйте переменную на URL HTTP-прокси.

aiogram авторизуется не тем логином

Вы передали логин и в URL, и объектом BasicAuth. Побеждает BasicAuth. Заодно проверьте, что aiohttp-socks стоит в том интерпретаторе, который запускает бота.

Telethon предупреждает, что нет python-socks

Словарь прокси задан, а зависимости нет, поэтому Telethon подключается без прокси. Выполните pip install "python-socks[asyncio]" и перезапустите.

Таймауты на резидентском выходе

python-telegram-bot по умолчанию ждёт пять секунд на соединение и пять на чтение. Поднимите connect_timeout и read_timeout в HTTPXRequest или переведите бота на IP датацентра или ISP.