Open Source • MIT License

TG WS Proxy
Accelerate Your Telegram Desktop

A local SOCKS5 proxy that routes Telegram traffic through WebSocket connections, significantly improving file upload and download speeds. The TG WS Proxy tool provides a seamless solution for optimizing your Telegram experience.

2,100+ Stars
74 Forks
Python
Download v1.1.1View Source
Terminal

# How TG WS Proxy routes traffic

Telegram Desktop → SOCKS5 (127.0.0.1:1080) → TG WS Proxy

TG WS Proxy → WSS (kws*.web.telegram.org) → Telegram DC

Why Choose TG WS Proxy?

Discover the powerful features that make this WebSocket proxy the ideal solution for enhancing your Telegram Desktop performance.

Faster File Transfers

TG WS Proxy accelerates file uploads and downloads by routing traffic through optimized WebSocket connections to Telegram data centers.

Secure Connection

All connections are encrypted using TLS through WebSocket Secure (WSS) protocol, ensuring your data remains private and protected.

Automatic Fallback

When WebSocket connections are unavailable, the proxy automatically switches to direct TCP connections for uninterrupted service.

Easy Configuration

Simple system tray application with GUI settings editor. Configure port, data centers, and logging with just a few clicks.

Command Line Support

For advanced users, TG WS Proxy offers full command-line interface with customizable arguments for port, DC IPs, and verbose logging.

Multi-DC Support

Intelligently routes traffic to the correct Telegram data center by extracting DC ID from MTProto obfuscation init packets.

How TG WS Proxy Works

Understanding the technical architecture behind this Telegram WebSocket proxy solution.

1

Local SOCKS5 Proxy

The application creates a local SOCKS5 proxy server on 127.0.0.1:1080. Telegram Desktop connects to this local endpoint.

2

Traffic Interception

TG WS Proxy intercepts connections to Telegram IP addresses and extracts the Data Center ID from MTProto obfuscation init packets.

3

WebSocket Connection

Establishes TLS-encrypted WebSocket connections to the corresponding DC throughkws{N}.web.telegram.org domains.

4

Smart Fallback

If WebSocket is unavailable (302 redirect), automatically switches to direct TCP connection for seamless operation.

Connection Flow Diagram

Telegram Desktop
SOCKS5 Proxy (127.0.0.1:1080)
TG WS Proxy Engine
WSS (kws*.web.telegram.org)
Telegram Data Center

Installation Guide

Get started with TG WS Proxy in minutes. Choose the installation method that works best for you.

Windows Quick Start

Easiest method for Windows users

  1. 1.Download TgWsProxy.exe from GitHub Releases
  2. 2.Run the executable - it opens with setup instructions
  3. 3.Right-click tray icon → "Open in Telegram" for auto-config
Download Latest Release
>_

Install from Source

For developers and advanced users

Install dependencies:

bash
pip install -r requirements.txt

Run Windows tray app:

bash
python windows.py

Or use console mode:

bash
python proxy/tg_ws_proxy.py [--port PORT] [--dc-ip DC:IP ...] [-v]

Configure Telegram Desktop

Automatic Setup

Right-click the tray icon and select "Open in Telegram" to automatically configure the proxy settings via tg://socks link.

Manual Setup

  1. 1. Open Telegram → Settings → Advanced → Connection type → Proxy
  2. 2. Add proxy with: Type: SOCKS5
  3. 3. Server: 127.0.0.1 Port: 1080
  4. 4. Leave username/password empty

Command Line Arguments

ArgumentDefaultDescription
--port1080SOCKS5 proxy port
--dc-ip2:149.154.167.220Target IP for DC (can specify multiple)
-v, --verboseoffEnable DEBUG logging

Frequently Asked Questions

Common questions about TG WS Proxy installation, usage, and troubleshooting.

Legal Disclaimer

Third-Party Website: This website (tgwsproxy.org) is an independent third-party resource created for technical documentation and navigation purposes only. It is not affiliated with, endorsed by, or officially connected to Telegram Messenger Inc. or the original project author.

No Warranty: The information provided on this website is for general informational purposes only. We make no representations or warranties of any kind, express or implied, about the completeness, accuracy, reliability, or suitability of the information.

Use at Your Own Risk: Any reliance you place on such information is strictly at your own risk. We shall not be liable for any loss or damage arising from your use of TG WS Proxy or any information on this website.

Trademarks: Telegram is a trademark of Telegram Messenger Inc. All other trademarks and copyrights are the property of their respective owners.