Telegram MTProto Setup

MediaFlow Proxy can stream videos directly from Telegram channels, groups, and DMs — with high-speed parallel chunk downloads and full seeking support. This page walks you through the one-time setup.

Prerequisites — get your Telegram API credentials

Before you start, you need a Telegram API ID and API Hash. These are tied to your Telegram account and free to obtain.

Open my.telegram.org/apps and log in with your Telegram phone number.
Create a new application — any name and short name are fine (e.g. "MediaFlow").
Note down the App api_id (a number) and App api_hash (a hex string).

You only need to do this once — the same credentials work for every device you set up.

Generate a session string via the web UI

The proxy's built-in web UI includes a Session String Generator that handles authentication with Telegram and produces the session string you need. No command line required.

Start the proxy and open the web UI — on Android, tap Open in Browser in the app; on other platforms, navigate to http://localhost:8888.
Go to the URL Generator page and select the Telegram tab at the top.
If you have an API password set, enter it when prompted.
Scroll down past the URL generator to the Session String Generator section.
Fill in the three fields:
- API ID — the number from my.telegram.org
- API Hash — the hex string from my.telegram.org
- Phone number — your Telegram account number in international format (e.g. +1234567890)
Click Send Code — Telegram sends a verification code to your Telegram app.
Enter the code and click Verify.
The session string is generated. The panel shows ready-to-copy config snippets for both environment variables and TOML:

APP__TELEGRAM__API_ID=12345678
APP__TELEGRAM__API_HASH=abcdef1234567890abcdef1234567890
APP__TELEGRAM__SESSION_STRING=<long string>

Apply the credentials

Android app

Open the Config tab in the MediaFlow Proxy app.
Enter the API ID, API Hash, and Session String in their respective fields.
Tap Save, then Restart — the Telegram proxy is now active.

Docker / environment variables

Add the three variables to your docker run command or Compose file:

docker run -d \
  -e APP__AUTH__API_PASSWORD=your-password \
  -e APP__TELEGRAM__API_ID=12345678 \
  -e APP__TELEGRAM__API_HASH=abcdef1234567890abcdef1234567890 \
  -e APP__TELEGRAM__SESSION_STRING="<session string>" \
  ghcr.io/mhdzumair/mediaflow-proxy-light:latest

TOML config file

[telegram]
api_id         = 12345678
api_hash       = "abcdef1234567890abcdef1234567890"
session_string = "<session string>"
max_connections = 8

Verify it's working

Once the proxy has restarted with the credentials, check the connection status:

http://localhost:8888/proxy/telegram/status?api_password=your-password

A healthy response looks like:

{ "connected": true, "session": "active" }

Usage

With the Telegram proxy active, stream any Telegram video by calling /proxy/telegram/stream. The URL Generator's Telegram tab builds these URLs for you — paste a t.me link or message reference, choose your options, and copy the result.

Endpoints

Method	Path	Description
`GET/HEAD`	`/proxy/telegram/stream`	Stream Telegram media
`GET/HEAD`	`/proxy/telegram/stream/<filename>`	Stream with filename hint for players
`GET`	`/proxy/telegram/info`	Get media metadata (size, MIME type, filename)
`GET`	`/proxy/telegram/status`	Session connection status

Stream parameters

The stream endpoint supports five ways to identify the media, tried in the order listed:

Priority	Required params	Optional extras	Notes
1	`d=<t.me URL>`	—	Accepts `https://t.me/channel/123` (public) or `https://t.me/c/123456789/456` (private)
2	`chat_id` + `message_id`	—	Recommended. Fetches a fresh file reference directly — never expires
3	`chat_id` + `document_id`	`message_id`	Scans recent chat history to find the document
4	`chat_id` + `file_id`	`file_size`	Decodes `file_id` to resolve the document; falls back to embedded reference if `file_size` is also supplied
5	`file_id` + `file_size`	—	Standalone Bot-API file_id; `file_size` is required for range/seek support

All modes also accept api_password when authentication is enabled.

Why modes 2–4 are better than `file_id` alone

A file_id contains a file_reference that is tied to the bot session that issued it — it expires and cannot be refreshed from a different session. When you supply chat_id + message_id (or document_id), the proxy fetches the message directly via MTProto and obtains a fresh reference from your own session, which never produces a file reference expired error.

Examples

# Mode 1 — t.me public link
curl -OJ "http://localhost:8888/proxy/telegram/stream?d=https://t.me/mychannel/42&api_password=secret"

# Mode 1 — t.me private channel link
curl -OJ "http://localhost:8888/proxy/telegram/stream?d=https://t.me/c/1234567890/42&api_password=secret"

# Mode 2 — chat_id + message_id (recommended, never expires)
mpv "http://localhost:8888/proxy/telegram/stream?chat_id=-1001234567890&message_id=42&api_password=secret"

# Mode 3 — chat_id + document_id
mpv "http://localhost:8888/proxy/telegram/stream?chat_id=-1001234567890&document_id=5678901234&api_password=secret"

# Mode 5 — standalone file_id (requires file_size)
mpv "http://localhost:8888/proxy/telegram/stream?file_id=BQACAgIAAxkB...&file_size=734003200&api_password=secret"

# Get media info before streaming
curl "http://localhost:8888/proxy/telegram/info?chat_id=-1001234567890&message_id=42&api_password=secret"

`/proxy/telegram/info` parameters

Accepts the same identification parameters as the stream endpoint (d, chat_id+message_id, chat_id+document_id, file_id). Returns:

{
  "file_size": 734003200,
  "mime_type": "video/mp4",
  "file_name": "movie.mp4",
  "duration": 5400,
  "width": 1920,
  "height": 1080,
  "dc_id": 4
}

[!NOTE] The session string authenticates as your Telegram account. Store it like a password — anyone who obtains it can access your Telegram media. It is stored locally on your device and never sent anywhere except to Telegram's own servers during stream requests.

[!NOTE] You only need to generate the session string once. If you reinstall the app or clear app data, repeat the generation steps above — your existing credentials from my.telegram.org remain valid.