How to Run a Python Telegram Bot Through a Proxy

· 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.

SOCKS5 or HTTP for bots on a fixed IP

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 support

The 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-socks

Create 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 an ImportError about the socksio package; install python-telegram-bot[socks]. aiogram needs aiohttp-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

Related articles

Proxies by platform
Telegram proxies: keep each account on its own static address
Telegram proxies with authenticated HTTP support: one static IPv4 per account in Singapore, the US or Vietnam, so a single spam flag stays with one session.
Proxy setup
Adding a Private HTTP Proxy Inside the Telegram App
Add an HTTP proxy with username and password inside Telegram on desktop, iOS and Android. Only Telegram changes IP; also block the P2P call IP leak.
Knowledge base
HTTP or SOCKS5: Picking the Proxy Protocol Your Software Needs
HTTP vs SOCKS5 proxy in plain terms: what each protocol carries, why HTTPS works through both, where UDP matters, and how to test which one a server speaks.
Proxy setup
Python requests through an authenticated proxy, step by step
Send Python requests through an authenticated HTTP(S) proxy: build the proxies dict, attach it to a Session, encode odd passwords, rotate a list, check the IP.
Knowledge base
Sending Go net/http requests through an authenticated proxy
Set a golang http client proxy with http.ProxyURL and a login, use SOCKS5 natively or with x/net/proxy, pick a proxy per request and read proxyconnect errors.
Knowledge base
Getting Java's HttpClient to authenticate to a proxy
Java HttpClient proxy authentication that works for HTTPS: the Authenticator, the disabledSchemes property that blocks Basic, OkHttp and SOCKS options.
Knowledge base
Configuring a proxy for HttpClient in C# and .NET
Route C# HttpClient proxy traffic with WebProxy and NetworkCredential, use SOCKS5 on .NET 6+, give each IHttpClientFactory client its own IP and fix 407s.
Free tools
Check proxies in bulk: status, exit IP and latency
Free online proxy checker: paste up to 100 ip:port:user:pass lines and see which proxies work, their exit IP and latency, plus what each failure result means.
Products
Dedicated datacenter proxies: one private IPv4 per customer
Private IPv4 proxies in the US, Vietnam, Japan, South Korea, Singapore, the UK and Hong Kong. One tenant per IP, HTTP(S) and SOCKS5, no traffic metering.
Products
Static ISP proxies: residential IPs on consumer networks
Static ISP proxies in the United States and Vietnam: fixed IPs registered to consumer internet providers, rented to one customer, with unmetered traffic.