Sessions

A session is what a client library needs to resume a logged-in account: a DC, its address and the auth key. opentele2 builds every format from a tdata account, and builds tdata back from each of them.

A session string or file is a logged-in account, exactly like the tdata folder it came from. Never paste one into an issue, a chat or a log.

The formats

Format	What it holds	Python	Node	Rust
Telethon string session (version `1`)	DC id, IPv4 or IPv6 address, port, auth key	`telethon_string_session`	`telethonStringSession`	`session::telethon::StringSession`
Telethon `.session` file (SQLite, version 8) + `.json`	the same row, plus the API profile and account fields	`SaveSessionJson`, `FromSessionJson`	`opentele2/telethon`	`session::telethon_file` (feature `telethon-sqlite`)
mtcute string session (version 3)	primary DC and address, self user id, test mode, auth key	`mtcute_string_session`	`toStringSession` (`opentele2/mtcute`)	`session::mtcute::StringSession`
grammers 0.11 `SessionData`	home DC, every production DC, the main DC key, the self user	—	—	`opentele2_grammers::session_data`

Which endpoint. Every conversion takes the first TCP endpoint of the account’s main DC from its stored MTP config when the account has one, and from the built-in production table otherwise. Telethon sessions take the IPv6 endpoint when you ask for it (ipv6 / use_ipv6) and the DC has one. A main DC without a usable endpoint fails with a bad-config error; an account without a key for its main DC fails with auth-key-not-found.

String sessions

strings.py


from opentele2._native import TData, mtcute_string_session, telethon_string_session
 
folder = TData.load("tdata")  # TData.load("tdata", "passcode") for a locked folder
account = folder.main_account
print(telethon_string_session(account))  # telethon_string_session(account, True) for IPv6
print(mtcute_string_session(account))

opentele2._native is the extension module the package is built on, typed by its _native.pyi stub. With a Telethon client at hand, Telethon’s own StringSession.save(client.session) gives the same string for a client from ToTelethon(..., UseCurrentSession).

strings.mjs


import { loadTdata, mtcuteStringSession, telethonStringSession } from 'opentele2'
import { toStringSession } from 'opentele2/mtcute'
 
const { mainAccount } = await loadTdata('tdata')
console.log(telethonStringSession(mainAccount)) // telethonStringSession(mainAccount, true) for IPv6
console.log(mtcuteStringSession(mainAccount))
console.log(toStringSession(mainAccount) === mtcuteStringSession(mainAccount)) // true

toStringSession is the form to hand to mtcute: client.importSession(...) or the TelegramClient constructor’s session string.

src/main.rs


use opentele2_core::session::{mtcute, telethon};
use opentele2_core::tdata::TData;
 
fn main() -> opentele2_core::Result<()> {
    let tdata = TData::load("tdata", b"", None)?;
    let account = tdata.main_account().expect("folder has an account");
    let string = telethon::StringSession::from_account(account, false)?.encode();
    let back = telethon::StringSession::decode(&string)?; // dc_id, addr, auth_key
    println!("{} {}", back.dc_id, back.addr);
    println!("{}", mtcute::StringSession::from_account(account, false)?.encode());
    Ok(())
}

Both types also decode a string back. Their Debug prints the key id only, never the key.

Telethon `.session` + `.json`

The pair is how many tools store a Telethon account: a Telethon SQLiteSession file (database version 8, the layout Telethon 1.45 writes and reads) and a .json companion with the API profile and account fields. opentele2 writes both byte for byte the same in every ecosystem, over the SQLite bundled in the core.

telethon.session
telethon.json

The companion starts with the profile keys app_id, app_hash, device, sdk, app_version, system_lang_pack, system_lang_code, lang_pack and lang_code, followed by the account keys (twoFA, role, id, phone, username, is_premium, first_name, last_name, proxy, ipv6 and the rest) and session_file, the base name of the pair. Loading a pair reads the profile back from it, so a session keeps announcing the device it was saved with.

pair.py


import asyncio
 
from opentele2.td import TDesktop
from opentele2.tl import TelegramClient
 
 
async def main():
    session_file, json_file = await TDesktop("tdata").SaveSessionJson("telethon.session")
    client = await TelegramClient.FromSessionJson("telethon.session")  # profile from the .json
    await client.connect()
 
 
asyncio.run(main())

SaveSessionJson(path, api=None, fetch_user_info=False) on a TelegramClient saves a connected client the same way; with fetch_user_info=True it fills id, phone, username, the names and is_premium from get_me().

pair.mjs


import { loadTdata, profile } from 'opentele2'
import { loadSessionPair, saveSessionPair } from 'opentele2/telethon'
 
const { mainAccount } = await loadTdata('tdata')
const paths = await saveSessionPair('telethon', mainAccount, profile('TelegramDesktop'))
const { rows, profile: saved, json } = await loadSessionPair('telethon')
console.log(paths.session, paths.json, rows.dcId, saved?.deviceModel, json.id)

writeSessionFile and readSessionFile handle the .session file alone; sessionCompanionText prints the companion.

src/main.rs


// cargo add opentele2-core --features telethon-sqlite
use opentele2_core::api::{self, Versions};
use opentele2_core::session::telethon_file::{self, SessionRows};
use opentele2_core::tdata::TData;
 
fn main() -> opentele2_core::Result<()> {
    let tdata = TData::load("tdata", b"", None)?;
    let account = tdata.main_account().expect("folder has an account");
    let rows = SessionRows::from_account(account, false)?;
    let path = telethon_file::write_session_file("telethon", &rows)?; // telethon.session
    let desktop = api::profile(api::Client::Desktop, &Versions::offline());
    std::fs::write("telethon.json", telethon_file::companion_text(&desktop, None))?;
    let rows = telethon_file::read_session_file(&path)?;
    println!("{} {}", rows.dc_id, rows.server_address);
    Ok(())
}

pair_paths, companion_json and read_companion are available without the feature.

grammers `SessionData`

opentele2_grammers::session_data(account) gives a grammers 0.11 SessionData: the main DC as home DC, every production DC with its first IPv4 and IPv6 endpoints (the stored config’s when there is one), the account’s key on the main DC only, and the self user in peer_infos. The updates state is empty, so grammers fetches it on first use.

src/main.rs


use grammers_session::storages::MemorySession;
use opentele2_core::tdata::TData;
 
fn main() -> opentele2_core::Result<()> {
    let tdata = TData::load("tdata", b"", None)?;
    let account = tdata.main_account().expect("folder has an account");
    let _session = MemorySession::from(opentele2_grammers::session_data(account));
    Ok(())
}

grammers’ SessionData and its DcOption print the raw auth key with Debug; do not log them.

Back to tdata

Every format goes back to a tdata folder. Two flags decide which session ends up in it:

Use the current session: the folder gets the client’s own auth key. Offline, and the same device keeps using it.
Create a new session: the existing client logs a new session in by QR code (with the 2FA password when the account has one) and the folder gets the new key, on the device of the API profile you pass. Needs the network.

back.py


import asyncio
 
from opentele2.api import API, CreateNewSession, UseCurrentSession
from opentele2.td import TDesktop
from opentele2.tl import TelegramClient
 
 
async def main():
    # From a .session + .json pair; the folder gets the pair's own key.
    tdesk = await TDesktop.FromSessionJson("telethon.session")
    tdesk.SaveTData("tdata_from_pair")
 
    # From a client: a new session on a generated device.
    client = TelegramClient("telethon.session")
    tdesk = await client.ToTDesktop(
        CreateNewSession, api=API.TelegramDesktop.Generate("windows", "my-id"), password=None
    )
    tdesk.SaveTData("tdata_new")
 
 
asyncio.run(main())

TDesktop.FromTelethon(client, flag, api, password) is the same as client.ToTDesktop(...); UseCurrentSession stores the client’s own session.

back.mjs


import { newTdata, saveTdata } from 'opentele2'
import { loadSessionPair } from 'opentele2/telethon'
 
// From a .session + .json pair.
const { rows, json } = await loadSessionPair('telethon')
const tdata = await newTdata([
  { index: 0, userId: BigInt(json.id), mainDc: rows.dcId, authKey: rows.authKey },
])
await saveTdata(tdata, 'tdata_from_pair')

From a live mtcute client, tdataFromClient(client, { passcode }) in opentele2/mtcute stores the client’s session; run qrLoginToNewClient(authorized, fresh, { profile, password }) first to store a new one.

src/main.rs


use grammers_session::SessionData;
use opentele2_core::tdata::{DrawSource, NEW_FOLDER_ACTIVE_INDEX, TData};
 
fn to_tdata(data: &SessionData) -> opentele2_core::Result<()> {
    let account = opentele2_grammers::account_from_session(data, 0)?;
    // No passcode, performance mode on, keys from the OS random source.
    let tdata =
        TData::new_with_draws(vec![account], b"", true, NEW_FOLDER_ACTIVE_INDEX, DrawSource::os())?;
    tdata.save_random("tdata_new")
}

With the client feature, client::tdata_from_client(&client, &session, passcode, rng) stores the session of a live grammers client; log a new one in with client::qr_login first to store a new session.

See the guides for full conversion and QR login recipes.

Sessions

The formats

String sessions

Telethon .session + .json

grammers SessionData

Back to tdata

Telethon `.session` + `.json`

grammers `SessionData`