Skip to Content
Getting startedIntroduction

Introduction

opentele2 is the Telegram client identity toolkit. A Telegram client is more than an auth key: it is the storage it keeps on disk, the session format of its library, the API id and device it announces in initConnection, the versions it claims, the transport it speaks and, for web clients, the browser it runs in. opentele2 reads, writes, converts and checks all of it, on one Rust core that Python, Node and Rust share.

What it covers

Telegram Desktop tdata

Read and write Telegram Desktop 7.3.1 folders: passcodes, several accounts, the MTP config.

Sessions

Telethon strings and .session + .json pairs, mtcute v3 strings, grammers 0.11 SessionData.

API profiles and devices

Eight official clients with weighted device catalogs; one unique id, one device, in every language.

initConnection fingerprints

Validation of the fields a client sends, tz_offset, msg_id offsets, layer and seven consistency checks.

Browser fingerprints

HTTP headers and full browser fingerprints from Bayesian networks, reproducible by seed.

MTProto crypto core

AES-256-IGE and -CTR, SHA, HMAC, PBKDF2 and PQ factorisation for Telethon, mtcute and grammers.

Live client versions, QR login with 2FA and session admin (list, print and terminate sessions) complete the set; see Client versions, the guides and the reference.

The packages

PackageRegistryRuntimeWorks over
opentele2PyPIPython 3.8+, abi3 wheelsTelethon 1.45
opentele2npmNode 18+, subpaths opentele2/mtcute and opentele2/telethonmtcute (@mtcute/node 0.32+)
opentele2-corecrates.ioRust—
opentele2-browsercrates.ioRust—
opentele2-versionscrates.ioRust, blocking HTTP—
opentele2-grammerscrates.ioRustgrammers 0.11
  • opentele2-core owns every format and rule: tdata, sessions, device catalogs, API profiles, initConnection checks, the consistency expectations and the MTProto client crypto. It is pure: no async, no network, no FFI and no unsafe code.
  • opentele2-browser generates browser headers and fingerprints. It is Apache-2.0; everything else is MIT.
  • opentele2-versions fetches the current official client versions and stable Chrome and Firefox.
  • opentele2-grammers turns tdata accounts into grammers sessions and API profiles into grammers connection params; its client feature adds QR login, session admin and the consistency checks.

How the pieces fit

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
Bindings are glue: the core owns the logic, the tables, the crypto and the randomness.

The Python wheel (PyO3) and the Node addon (napi-rs) are thin layers over the same core. Each one converts values, calls the core and adapts the result to its client library: Telethon in Python, mtcute in Node, grammers in Rust. Name tables, texts, error codes and session JSON shaping all come from the core, so the three ecosystems give the same answers, and the Rust, Python and Node test suites check them against the same golden vectors.

Targets: Telegram Desktop 7.3.1 tdata and Telethon 1.45, schema layer 230.

Warning:

A tdata folder, a session string or a .session file is a logged-in account. Anyone who holds one can act as you. Never share them, never commit them, and keep them out of logs.

Where to go next

Installation

Requirements and install commands for pip, npm and cargo, with the optional features.

Quick start

Load a tdata folder and get a Telethon, mtcute or grammers session from it.

Concepts

How opentele2 models tdata, sessions, profiles, fingerprints, crypto and versions.

Guides

Task-by-task recipes: conversions, QR login with 2FA, session admin and versions.

Last updated on
Installation