EN 中文 RU

Independent Guide

TG WS Proxy
A smarter path for Telegram Desktop traffic

TG WS Proxy is a local SOCKS5 proxy. It routes Telegram DC traffic through WSS (`kws*.web.telegram.org`) and falls back to direct TCP when needed.

Download Releases View Source

Disclaimer: this site is independent and not affiliated with Telegram or the project maintainers.

License

MIT License

Build Pipeline

GitHub Actions + PyInstaller

Latest Release

v1.2.1 (2026-03-22)

How It Works

  1. Telegram Desktop connects to local SOCKS5 at 127.0.0.1:1080.
  2. The proxy identifies Telegram target IPs and extracts DC metadata from MTProto obfuscation init packets.
  3. It prefers TLS WebSocket links to `kws*.web.telegram.org` (binary protocol).
  4. MTProto payloads are forwarded frame-by-frame to avoid handshake issues from merged packets.
  5. If WS returns 302/redirect-like failures, it automatically downgrades to direct TCP.
Telegram Desktop
  -> SOCKS5 127.0.0.1:1080
  -> TG WS Proxy
  -> WSS kwsN.web.telegram.org (/apiws)
  -> Telegram DC

Desktop-Friendly

Windows tray GUI, macOS app package, Linux package, and CLI mode are available.

Traffic Strategy

Telegram IP ranges are detected, with separate paths for DC and media/non-media traffic.

Configurable

Supports --port and multiple --dc-ip entries for network-specific tuning.

Stability Features

Connection pooling, cooldown handling, and automatic fallback reduce reconnect jitter.

Quick Start

1. Download

Get `TgWsProxy_windows.exe`, `TgWsProxy_macos_universal.dmg`, or `TgWsProxy_linux_amd64.deb` from Releases.

2. Launch Proxy

Default listener is 127.0.0.1:1080. Desktop builds provide tray controls and logs.

3. Set SOCKS5 in Telegram Desktop

Server 127.0.0.1, port 1080, and leave username/password empty.

tg-ws-proxy --port 1080 \
  --dc-ip 2:149.154.167.220 \
  --dc-ip 4:149.154.167.220 -v

Latest Changes

  1. Release notes are loaded from upstream GitHub Releases.
  2. If this section looks stale, open the source repository release page.

Release Files (v1.2.1)

Partner Offer

NordVPN

A VPN option for users who need additional privacy and cross-region access tools.

View Offer

Disclosure: This section may contain affiliate links. If you buy through these links, we may earn a commission at no extra cost to you.

Community Insights

Mobile Status (Current)

The mainline project is focused on Telegram Desktop. Android usage exists in community experiments (Termux/ports), but behavior may vary by device and network.

Phone via Your PC (LAN)

A maintainer-confirmed approach for local networks: run proxy host as 0.0.0.0 on your PC, then set your phone Telegram SOCKS to the PC LAN IP and port.

Media Not Loading

One frequent community symptom is \"chat works, media fails\". A commonly shared workaround is testing additional DC mapping such as `203:149.154.167.220`.

Remote Exposure Caution

For cross-network usage, you would need public IP and port forwarding. Maintainer guidance warns this is generally not the recommended default path for SOCKS.

FAQ

Why might acceleration be limited sometimes?

This is a partial optimization approach. Results depend on routes, region, ISP, and Telegram-side conditions.

Do I need a third-party remote proxy server?

No. It runs as a local process and forwards traffic to Telegram domains and nodes.

What if antivirus flags the binary?

The README mentions possible false positives. Download from official Releases and verify files yourself.

Will this affect Telegram account safety?

It works as a local traffic proxy and does not change your credentials or Telegram authentication flow.

Does it log my message content?

It includes runtime logs for connection and debugging status. Treat logs as sensitive operational data.

Is Telegram mobile supported?

The project is primarily designed for Telegram Desktop workflows.