How to Run a Python Telegram Bot Through a Proxy
By the ProxyV4 Engineering Team · Updated:
To use a Telegram Bot API proxy in Python, give your framework's HTTP client a proxy URL: in python-telegram-bot v20.7 and later call .proxy() and .get_updates_proxy() on ApplicationBuilder, and in aiogram 3 create AiohttpSession(proxy=...). Both accept http:// and socks5:// URLs with a username and password. The proxy covers the outbound calls your bot makes to api.telegram.org, including long polling.
How a Telegram Bot API proxy works in Python
A polling bot never opens a port on your machine. It sends HTTPS requests to https://api.telegram.org/bot<token>/getUpdates and waits for new updates, then sends more requests such as sendMessage to reply. All of that is outbound HTTPS, so a normal HTTP proxy (using CONNECT) or a SOCKS5 proxy can carry it. The TLS session runs end to end between your bot and Telegram; the proxy sees only the destination host.
Typical reasons to add a proxy: a corporate or hosting network that allows outbound traffic only through a proxy, a firewall rule on your side that should match one fixed egress IP, or running several bots for different clients that you want to keep on separate addresses. Telegram's Bot API terms and anti-spam rules apply the same way with or without a proxy.
Webhooks are not proxied
With webhooks, Telegram connects to your public HTTPS URL to deliver updates. That inbound traffic does not pass through your outbound proxy, so the proxy only matters for the calls your bot makes back, such as sendMessage. Most proxy setups therefore use long polling.
HTTP or SOCKS5?
Both work for the Bot API. HTTP needs no extra packages in either library; SOCKS5 needs an extra dependency but is handy when one line also serves non-HTTP tools. The trade-offs are explained in HTTP vs SOCKS5 proxies.
python-telegram-bot proxy setup (v20.7 and later)
python-telegram-bot uses httpx. HTTP proxies work out of the box; for SOCKS5 install the socks extra, which the library's documentation names for that purpose.
pip install "python-telegram-bot>=21" # HTTP proxy
pip install "python-telegram-bot[socks]>=21" # adds SOCKS5 supportThe library keeps two request objects: one for getUpdates and one for every other Bot API call. That is why ApplicationBuilder has both .proxy() and .get_updates_proxy(). Set only the first and your long polling still goes direct, which is the most common reason a "proxied" bot still fails on a blocked network.
from telegram import Update
from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes
PROXY = "http://USER:PASS@IP:PORT" # or "socks5://USER:PASS@IP:PORT"
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
await update.message.reply_text("Hello from behind a proxy.")
app = (
ApplicationBuilder()
.token("BOT_TOKEN")
.proxy(PROXY) # sendMessage and other Bot API calls
.get_updates_proxy(PROXY) # getUpdates (long polling)
.connect_timeout(10)
.build()
)
app.add_handler(CommandHandler("start", start))
app.run_polling()Both methods were added in version 20.7. On 20.0 to 20.6 the equivalents were .proxy_url() and .get_updates_proxy_url(), which version 22.0 removed, so upgrade rather than mixing names. If your password contains @, : or /, percent-encode it with urllib.parse.quote(password, safe="") before building the URL.
Passing your own HTTPXRequest
If you already build custom request objects, for example to set pool size, set the proxy inside them instead of on the builder, and pass one to .request() and one to .get_updates_request(). Use one approach or the other, not both.
from telegram.ext import ApplicationBuilder
from telegram.request import HTTPXRequest
PROXY = "socks5://USER:PASS@IP:PORT"
app = (
ApplicationBuilder()
.token("BOT_TOKEN")
.request(HTTPXRequest(proxy=PROXY, connect_timeout=10, read_timeout=10))
.get_updates_request(HTTPXRequest(proxy=PROXY, connect_timeout=10))
.build()
)In current versions, python-telegram-bot adds the polling timeout from run_polling() (10 seconds by default) to the read timeout of getUpdates, so you rarely need large read timeouts for polling. Repeated httpx.ConnectTimeout errors point at the proxy address, port or mode instead.
aiogram proxy setup (version 3)
aiogram 3 uses aiohttp, and its proxy support goes through the aiohttp-socks package, which the aiogram documentation asks you to install for proxy use. With it, AiohttpSession accepts http://, socks4:// and socks5:// URLs.
pip install aiogram aiohttp-socksCreate the session with the proxy URL and pass it to Bot. Every request that bot makes, including polling, then goes through the proxy.
import asyncio
from aiogram import Bot, Dispatcher
from aiogram.client.session.aiohttp import AiohttpSession
from aiogram.filters import CommandStart
from aiogram.types import Message
dp = Dispatcher()
@dp.message(CommandStart())
async def start(message: Message) -> None:
await message.answer("Hello from behind a proxy.")
async def main() -> None:
session = AiohttpSession(proxy="socks5://USER:PASS@IP:PORT")
bot = Bot(token="BOT_TOKEN", session=session)
await dp.start_polling(bot)
asyncio.run(main())Credentials with special characters
Instead of embedding the login in the URL, you can pass a tuple of URL and aiohttp.BasicAuth. aiogram's documentation says the BasicAuth values win if both are given, which avoids encoding problems with unusual passwords.
from aiohttp import BasicAuth
from aiogram.client.session.aiohttp import AiohttpSession
session = AiohttpSession(proxy=("http://IP:PORT", BasicAuth("USER", "PASS")))Test the proxy before starting the bot
When a bot fails to start, test the route outside the framework first. This script prints the proxy's exit IP and calls getMe, which returns your bot's details if the token and proxy both work. It uses socks5h:// so DNS is resolved by the proxy; use http:// instead if your line is in HTTP mode.
import requests
TOKEN = "BOT_TOKEN"
PROXY = "socks5h://USER:PASS@IP:PORT" # needs: pip install "requests[socks]"
proxies = {"http": PROXY, "https": PROXY}
print(requests.get("https://proxyv4.com/api/my-ip", proxies=proxies, timeout=10).text)
r = requests.get(f"https://api.telegram.org/bot{TOKEN}/getMe", proxies=proxies, timeout=10)
print(r.status_code, r.json())Compare the printed IP with your proxy line, or open the my IP tool in a browser using the same proxy. A 401 from getMe means a wrong bot token; a proxy error before that means the proxy settings are wrong.
Fixing common Telegram proxy errors
Most failures fall into a few groups. Read the exception type before changing code.
- 407 or "proxy authentication required". Wrong username or password, or an unencoded special character; see 407 Proxy Authentication Required.
- Missing SOCKS dependency. With a
socks5://URL and no SOCKS support installed, httpx raises anImportErrorabout thesocksiopackage; installpython-telegram-bot[socks]. aiogram needsaiohttp-socks. - Connection refused or timeouts. The port or mode is wrong. If the order is set to HTTP only, a
socks5://URL fails, and the other way round. - Replies work but polling fails. In python-telegram-bot you set
.proxy()but not.get_updates_proxy(). - Conflict: terminated by other getUpdates request. Two copies of the same bot are polling; stop one. This is not a proxy issue.
Running Telegram bots on a fixed proxy with ProxyV4
A bot needs a steady route more than anything else, and a static IP suits that. ProxyV4 sells private datacenter IPv4 in seven countries and static ISP proxies in the United States and Vietnam. Each IP has one tenant for the whole term and stays the same while the proxy is active; renewing before expiry keeps the address, so firewall rules that reference it keep working. Traffic on private IPv4 and static ISP is not metered, so bots that send photos or files do not add to the bill. More on Telegram use is on the Telegram proxy page, and the Telegram apps themselves are covered in the Telegram proxy setup guide.
Every proxy supports HTTP(S) and SOCKS5 with username and password, delivered as ip:port:user:pass. On the order's page you choose HTTP only, SOCKS5 only or both on the same port; switching modes can move the proxy to a new port, so copy the line again afterwards and update the bot's URL.
Where it does not fit: ProxyV4 sells no rotating or mobile proxies, and if your bot setup depends on UDP (for example voice tooling outside the Bot API), ask support through a ticket before ordering. IPv6 proxies are a separate product that only works on IPv6-ready sites; the Bot API is reachable over IPv4. Live per-IP prices are on the pricing page, and one IP is enough to start. A proxy that fails for a technical reason is credited to your balance under the refund policy.
Frequently asked questions
Can python-telegram-bot use a SOCKS5 proxy?
Yes. Install python-telegram-bot[socks] and pass a socks5://USER:PASS@IP:PORT URL to .proxy() and .get_updates_proxy().
Why does my bot reply but never receive updates through the proxy?
In python-telegram-bot, getUpdates uses its own request object. Set .get_updates_proxy() as well as .proxy().
Does aiogram 3 need extra packages for a proxy?
Yes. Install aiohttp-socks, then pass the proxy URL to AiohttpSession(proxy=...).
Can one ProxyV4 line serve both HTTP and SOCKS5 bots?
Yes. Set the order to both modes on the order's page and the same port accepts HTTP and SOCKS5 with your username and password.
Will the bot's IP change when I renew?
No. The IP stays the same while the proxy is active, and renewing before expiry keeps the same address.
SOCKS5 or HTTP for bots on a fixed IP
Run your Telegram bots through a private IPv4 address with HTTP(S) and SOCKS5 on one line and unmetered traffic. Start with a single IP.
See live prices