Set Up a Telegram Proxy on Desktop (Windows, Mac, Linux)
Set Up a Telegram Proxy on Desktop (Windows, Mac, Linux)
Adding a proxy to Telegram on the desktop is a five-minute job once you know where the menu lives and what each field actually does. The harder part is not the clicking. It is understanding what a proxy does and does not change about how Telegram sees you, and whether the IP you just pasted is worth trusting with an account you care about. This guide walks the exact UI paths on Windows, macOS, and Linux, explains MTProto versus SOCKS5 without the marketing, and then gets honest about IP quality, because a working proxy and a safe proxy are not the same thing.
We run managed Telegram hosting on dedicated Singapore hardware, so we see what happens when people connect serious accounts through throwaway proxies. The mechanics below are the same whether your proxy cost nothing or cost real money. The difference shows up later.
what you will end up with
By the end you will have Telegram Desktop or the native macOS app routing its connection through a proxy server you configured, verified that traffic is actually going through it, and you will be able to switch it on and off in one click. You will also understand the trade-offs well enough to decide whether the IP you are using is good enough for your account, or whether you are quietly setting yourself up for a verification loop or a ban.
A proxy changes the network path Telegram takes to reach its servers. It does not change your account, your phone number, or the device fingerprint Telegram records when you sign in. Those are separate concerns, and we cover the fingerprint piece in the difference between desktop and mobile clients. Keep the two ideas apart in your head and the rest of this is straightforward.
before you start
You need three things in hand before you open any menu.
1. The proxy credentials. For MTProto you need a server host or IP, a port, and a secret (a long hex string). For SOCKS5 you need a host, a port, and usually a username and password. If you only have a tg://proxy?... or https://t.me/proxy?... link, that is fine. Telegram can import the whole thing for you, and we cover that path below.
2. A clear idea of what the proxy is for. If you just want to reach Telegram on a network that blocks it, almost any working proxy does the job. If you are connecting an account that matters, the quality and type of the IP matter a great deal. Read why Telegram bans accounts before you connect anything important through a random free server.
3. A way to verify it worked. Knowing your real IP before you start makes the after-check meaningful. We will use Telegram’s own connection indicator plus an external leak test later.
One thing worth settling now: MTProto versus SOCKS5. MTProto is Telegram’s own proxy protocol. It is designed to look like ordinary traffic, which helps it survive in places that actively block proxies, and it only works with Telegram. SOCKS5 is a general protocol that routes any traffic, not just Telegram. SOCKS5 is more flexible and easier to source, but it is also easier for a network to spot and block. For a deeper comparison including cloud phones, see MTProto vs SOCKS5 vs cloud phone and what an MTProto proxy actually is.
the step-by-step
The desktop client (Telegram Desktop, often called tdesktop) is the same on Windows and Linux. The native macOS app is laid out slightly differently, so it gets its own pass.
Telegram Desktop on Windows and Linux
1. Open Settings. Click the hamburger menu (three lines) at the top left of the chat list, then choose Settings. On some builds you reach it through the gear icon.
2. Go to Advanced. In Settings, click Advanced. Scroll to the Connection type section near the top.
3. Open Connection type. Click the current value (it will say “Default connection type”). A dialog opens with three options: Automatic, Use custom TCP/HTTP proxy, and the per-proxy list.
4. Choose to add a proxy. Select “Use custom proxy” or “Add proxy”. Telegram Desktop lets you save multiple proxies and toggle between them, which is genuinely useful.
5. Pick the protocol. Choose SOCKS5 or MTProto at the top of the add-proxy form. The fields change depending on which you pick.
6. Fill in the fields. For SOCKS5: Hostname, Port, and optionally Username and Password. For MTProto: Hostname (or Server), Port, and Secret. Paste the secret exactly, with no leading or trailing spaces.
7. Save and enable. Click Save. The new proxy appears in the list with a toggle. Switch it on. A small shield or proxy icon appears near the top of the chat list when a proxy is active.
That is the whole flow. If your network blocks Telegram entirely, you may need to enable the proxy before Telegram can connect at all, which means typing the details while offline. The client handles this fine.
Importing a tg:// proxy link
If someone handed you a link instead of raw fields, you do not need to parse it by hand.
1. Click the link. If Telegram Desktop is installed and registered as the handler, clicking a tg://proxy?... or https://t.me/proxy?... link opens Telegram and shows an “Enable proxy?” prompt with the server pre-filled. Confirm it.
2. Or paste it manually. If clicking does nothing, copy the link, then in the add-proxy dialog some builds offer a “Paste from clipboard” option that reads the whole link and fills every field. Otherwise read the link structure below and copy each value into its field.
A tg:// proxy link is just the same fields encoded into a URL. The format looks like this:
# MTProto link
tg://proxy?server=HOST&port=PORT&secret=HEXSECRET
# SOCKS5 link
tg://socks?server=HOST&port=PORT&user=USERNAME&pass=PASSWORD
# tdata folder locations (where the desktop client stores your session)
Windows: %AppData%\Telegram Desktop\tdata
macOS: ~/Library/Application Support/Telegram Desktop/tdata
Linux: ~/.local/share/TelegramDesktop/tdata
Each value after the & maps directly to a field in the add-proxy form. The tdata path is included because your session lives there, and if you ever move an account between machines that folder is what travels. We explain that carefully in what a tdata folder is and how to export tdata safely; do not copy it casually, because a session moved to a wildly different IP is a classic trigger for a verification challenge.
The native macOS app
The App Store macOS client (the Swift one, sometimes called Telegram for macOS) is not the same as Telegram Desktop, and its menu is laid out differently.
1. Open Preferences. Telegram menu in the top bar, then Preferences, or press Command and comma.
2. Find Proxy Settings. Look under Advanced, or for a Data and Storage / Network section depending on the version. There is a “Connection” or “Proxy Settings” entry.
3. Add a server. Click “Add Proxy” or the plus button. Choose SOCKS5 or MTProto.
4. Enter the details. Same fields as the desktop client: host, port, and either username/password (SOCKS5) or secret (MTProto).
5. Enable and use for calls if needed. Toggle the proxy on. The macOS app has a separate switch for routing calls through the proxy; enable it if you need voice traffic covered too.
If you also run Telegram on a phone, the mobile setup follows the same logic with a different UI. We have step-by-steps for Android and iPhone.
Verifying it actually works
Configuring a proxy and using a proxy are not the same. Confirm both.
1. Check the proxy indicator. When a proxy is active and connected, Telegram shows a small shield or proxy icon. If it spins or shows an error, the credentials or the server are wrong.
2. Confirm Telegram still loads messages. If chats sync and you can send a message, traffic is flowing through the path you set.
3. Run a leak test. A connected indicator does not prove there are no leaks. WebRTC, DNS, or fallback paths can expose your real IP. Walk through how to test if your Telegram proxy is leaking and actually do it before trusting the setup.
what can go wrong
A few failure modes come up again and again.
Wrong secret or extra whitespace. MTProto secrets are long. Copy-pasting from chat apps sometimes adds a trailing space or a hidden character. If MTProto refuses to connect, retype or re-paste the secret cleanly.
Port blocked by your network. Some networks block the port your proxy uses. If the server is reachable from elsewhere but not from your current network, the network is the problem, not your config. MTProto on common ports tends to survive restrictive networks better than SOCKS5.
The proxy works but the IP is flagged. This is the quiet one. The proxy connects, Telegram loads, everything looks fine, and then your account hits a verification wall or gets limited days later. That is almost never a config issue. It is the IP. Free and shared datacenter proxies are used by thousands of people, and Telegram’s systems treat them accordingly. A datacenter IP that hundreds of strangers have logged in through is a different risk profile than a clean mobile IP. This is the whole reason mobile IP quality matters, covered in what a mobile IP is and why Telegram cares.
IP keeps changing between sessions. Rotating proxies that hand you a different IP every connection look great for scraping and terrible for a logged-in account. Telegram notices when your session jumps countries between messages. For a real account you want a stable, dedicated IP, which is the argument in what a dedicated mobile IP is.
Account asks for a login code on a new IP. If you connect an existing account through a proxy in a new country, Telegram may challenge you. That is the system working, not breaking. Expect it when the IP location differs sharply from where the account usually lives.
how this looks on managed hosting
Everything above is the do-it-yourself path: you find a proxy, paste it into the client, and hope the IP holds up. It works, and for casual unblocking it is genuinely all you need.
For an account that earns or matters, the proxy is only one piece. The IP needs to be a real mobile IP, dedicated to you rather than shared, and stable over time. The device fingerprint should be consistent. The session should not jump around. That is the gap managed hosting fills.
On our side, accounts run on dedicated Singapore hardware with mobile IPs on real local carriers (SingTel, M1, StarHub, and Vivifi), plus a Samsung cloud-phone fleet for cases where a desktop session is not the right shape at all. You bring your own number; we do not sell accounts and we do not touch your number beyond hosting it. The point is a clean, stable, local mobile IP that does not look like the shared datacenter pool every free proxy lives in. The difference between a Singapore mobile IP and a generic proxy is laid out in the Singapore mobile IP advantage for Telegram.
If you are running several accounts or the device-limit math is starting to bite, the cloud-phone approach changes the picture, since each account gets its own consistent device instead of many sessions stacked on one machine. We cover that in device limits and cloud-phone hosting and the practical mechanics of keeping your own number in BYO-number Telegram hosting explained.
To be clear about what a proxy alone gives you: network reach and a different visible IP. What it does not give you is a guarantee that the IP is clean, dedicated, or stable, and those three things are what actually keep an account healthy over months. A working proxy is the start of the conversation, not the end of it.
If you want the underlying protocol details before deciding, the official client documentation lives at telegram.org, and our companion infrastructure for general mobile-proxy use is at singaporemobileproxy.com.
final word
Adding a proxy to Telegram Desktop or the macOS app is easy: Settings, Advanced, Connection type, pick MTProto or SOCKS5, fill the fields, save, verify. Spend the saved time on the part that matters, which is whether the IP behind that proxy is good enough for the account you are connecting. A flagged or rotating IP will undo a perfect configuration.
If you would rather skip the proxy roulette and run your account on dedicated Singapore hardware with real local mobile IPs and your own number, that is exactly what we host. See how it works on the home page and use code TGYT when you reach out.