Skip to Content

opentele2 2.0

The Telegram client identity toolkit.

One Rust core for tdata, sessions, official API profiles with realistic devices, fingerprint checks and browser fingerprints — shipped for Python, Node and Rust.

pip install opentele2
  • Python 3.8+
  • Node 18+
  • Rust crates
  • MIT
Client identitydeterministic by seed
API profileseed "my-id"
API.TelegramDesktop.Generate("windows", "my-id")
api_id
2040
device_model
Vostro 3520
system_version
Windows 11 x64
app_version
7.3.1 x64
lang_pack
tdesktop
system_lang_code
en-US

initConnection validation: 0 issues

Browser fingerprintseed 42
FingerprintGenerator(screen=Screen(max_width=1920)).generate(seed=42)

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.3 Safari/605.1.15

platform
MacIntel
screen
1470 × 956 @2x
hardwareConcurrency
8
webgl
Apple GPU · Apple Inc.
Accept-Language
en-US;q=1.0
Same seed, same output in Python, Node and Rust.

What's inside

Everything a client identity is made of.

Storage, sessions, the profile a client announces, the checks that keep it believable and the crypto underneath — one library, the same behaviour in every ecosystem.

Telegram Desktop tdata

Read and write tdata folders of Telegram Desktop 7.3.1, passcode-locked ones and several accounts per folder included.

  • tdata/
  • key_dataslocal key
  • D877F783D5D3EF8Csauth keys
  • D877F783D5D3EF8C/
  • mapsaccount map
  • configsMTP config

TDF$ containersversion 7003001up to six accounts

Every session format

Telethon, mtcute and grammers sessions from tdata, and tdata back from a client.

Telethon string session1ApWapzMBu…version 1 · DC 2 · 149.154.167.51:443 · auth key
Telethon .session
SQLite v8 + .json
mtcute
string v3
grammers 0.11
SessionData
API profiles and devices

Official desktop, mobile and web profiles with weighted device catalogs; one unique id, one device.

client · api_id · lang_pack
Desktop
2040
tdesktop
Android
6
android
Telegram X
21724
android
iOS
10840
ios
macOS
2834
macos
Web K
2496
macos
initConnection validation

Layer, lang pack, tz_offset, msg_id offset and version consistency of the parameters a client sends; the Python package adds a transport recommendation.

validate_init_connection_params(1, "Desktop", …, strict=True)

errorApiIdMismatchapi_id 1 does not match lang_pack 'tdesktop' (expected 2040)

  • UnknownLangPack
  • ShortLangCode
  • MissingRegion
  • EmptyDeviceModel
  • AppVersionMajor
  • AndroidSdkRange

layer 230tz_offsetmsg_id offset

Browser fingerprints

HTTP headers and full browser fingerprints sampled from Bayesian networks, based on browserforge and the Apify datapoints, reproducible by seed.

HeaderGenerator(browser="chrome", os="windows").generate(seed="my-id")

User-AgentMozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36

  • generate_headers(Some("my-id"), …)
  • HeaderGenerator(…).generate(seed="my-id")
  • generateHeaders(…, 'my-id')

byte-identical output for one seed

Seven consistency checks

A profile against a live session. QR login with 2FA, then list, print and terminate sessions.

Consistency: 7/7 checks passed

  1. get_config
  2. nearest_dc
  3. current_session
  4. layer_match
  5. lang_pack
  6. app_update
  7. terms_of_service
Live client versions

Current official client versions from the Telegram release sources, plus stable Chrome and Firefox.

Versions::offline()
Telegram Desktop
7.3.1
Telegram Android
13.0.3
Telegram iOS
13.0
Telegram for macOS
13.0
Chrome
155.0.0.0
Firefox
150.0
Rust crypto core

The MTProto client crypto for Telethon, mtcute and grammers, on the Rust core.

AES-CTR on 1 MiB0.9 mspyaes 3.6 s
  • AES-256-IGE
  • AES-256-CTR
  • SHA-1
  • SHA-256
  • HMAC
  • PBKDF2
  • PQ factorisation
Telethon
cryptg + bridge
mtcute
ICryptoProvider
grammers
Rust

Architecture

One core. Three ecosystems.

The logic, the device tables, the crypto and the randomness live in opentele2-core. The Python and Node packages are thin bindings, and the Rust crates build on it directly.

opentele2 architectureThe Rust crate opentele2-core sits in the centre. The Python package on PyPI binds it through PyO3 and works with Telethon; the Node package on npm binds it through napi-rs and works with mtcute; the Rust crates opentele2-browser, opentele2-versions and opentele2-grammers build on it, the last one for grammers.PyO3napi-rscratesONE RUST COREopentele2-coretdata · sessions · API profiles · devicesinitConnection checks · MTProto cryptoPythonPyPI · opentele23.8+ · abi3 wheelsNodenpm · opentele218+ · /mtcute · /telethonRustcrates.io · opentele2-*browser · versions · grammersTelethon1.45mtcute0.32+grammers0.11opentele2 architectureThe Rust crate opentele2-core sits in the centre. The Python package on PyPI binds it through PyO3 and works with Telethon; the Node package on npm binds it through napi-rs and works with mtcute; the Rust crates opentele2-browser, opentele2-versions and opentele2-grammers build on it, the last one for grammers.PyO3napi-rscratesONE RUST COREopentele2-coretdata · sessions · profiles · devicesfingerprint checks · MTProto cryptoPythonPyPI · opentele23.8+ · abi3 wheelsNodenpm · opentele218+ · subpathsRustcrates.ioopentele2-*Telethon1.45mtcute0.32+grammers0.11
PyPI opentele2 binds the core through PyO3, npm opentele2 through napi-rs; grammers users take the crates.
Load a tdata folder and write a client session
convert.py
import asyncio from opentele2.api import UseCurrentSession from opentele2.td import TDesktop async def main(): tdesk = TDesktop("tdata") # TDesktop("tdata", passcode="...") for a locked folder client = await tdesk.ToTelethon("telethon.session", UseCurrentSession) await client.connect() print(await client.get_me()) asyncio.run(main())

Performance

Fast by default.

The tdata loader and the MTProto client crypto run in the Rust core, in every ecosystem.

Load a one-account tdata folder

0.24ms

1.08 ms with a pure-Python loader

best of 3 × 200 loads

AES-CTR on 1 MiB

0.9ms

3.6 s with pyaes (pure Python)

MTProto client crypto

Measured on one machine.

Get started

From a tdata folder to a connected client.

Three steps, in whichever ecosystem you picked above.

Install the package

pip install opentele2

Load a tdata folder

Point TDesktop, loadTdata or TData::load at the folder; pass the passcode for a locked one.

Write a session and connect

Write a Telethon, mtcute or grammers session and connect with an official API profile.