Telegram tdata Telethon Pyrogram: A Developer's Field Guide to Account Formats, Conversion and Auth Failures

Match the account format to the runtime that will hold it

The Telegram tdata Telethon Pyrogram question resolves faster than most buyers expect once you stop treating format as a packaging detail. If a human or an anti-detect browser profile will touch the account, order tdata. If a script drives it with nobody watching, order session strings and name the library. Everything else in this article is detail hanging off that one decision.

Two more rules save first-time developer orders. Telethon and Pyrogram session strings are not interchangeable even though both wrap the same underlying key material, so “session string” alone is an incomplete specification. And conversion runs one direction cheaply: tdata exports down into either library format, while a session string will not rebuild a usable tdata folder. When the deployment plan is still moving, buy tdata and export from it.

This is the engineering-side companion to our bulk Telegram buying and pricing guide, which covers tiers, farm sizing and DM ceilings. Here the subject is bytes, libraries and error codes.

What is actually inside a tdata folder

tdata is the local state directory Telegram Desktop writes so it can restart without asking for a login code. It is not a credential file in the way buyers imagine. It is a small encrypted store containing the authorization key, the datacenter the account is bound to, cached settings and, depending on how the account was used, cached chat data.

The files that matter

A minimal folder holds a key_datas file, a map or mapN file, and one or more directories with long hexadecimal names, typically alongside a settings blob. The hex directories are the per-account payload. The key_datas file carries the local key that decrypts the rest, and it is derived from the desktop local passcode when one is set.

That derivation is the practical catch. A tdata folder protected by a local passcode is unusable without the passcode, and the passcode is almost never included by default. Put it in the order spec.

Why a partial copy fails

Copy the whole directory or nothing. Buyers regularly try to slim a batch by dropping cached media directories, then find the folder will not open. The map file indexes what should be present, and a folder whose contents disagree with its own index is treated as corrupt rather than repaired. Zip the directory at the root, transfer it intact, and unzip into a clean path with no existing Telegram Desktop state in it.

What a session string encodes, and why two libraries disagree

A session string is the API-side equivalent of tdata, compressed to one line of text. Underneath both formats sits the same object: a 256-byte MTProto authorization key tied to a specific datacenter. Everything else is bookkeeping around it, and the bookkeeping is where the libraries part ways.

Telethon StringSession

Telethon packs a version marker, the datacenter id, the server address, the port and the auth key, then base64-encodes the result. The string opens with a version character, which is why Telethon strings are easy to spot by eye. Telethon does not store the API id inside the string, so the API pair you supply at construction time is entirely your responsibility.

Pyrogram string sessions

Pyrogram packs a different set: datacenter id, API id, a test-mode flag, the auth key, the user id and a bot flag. Because the API id is baked in, a Pyrogram string carries an implicit expectation about which application it belongs to. Hand it a different API id at construction and you have created a quiet inconsistency that shows up later as unexplained sign-in prompts.

The SQLite .session file

Both libraries also support a file-backed session, and both use SQLite, with incompatible schemas. File sessions are convenient for a handful of accounts and painful at scale, because SQLite locks. Two workers opening one .session file produce database is locked under load, and the fix is not a longer timeout. Move to string sessions held in your own store once you pass roughly fifty accounts.

Telegram tdata Telethon Pyrogram compatibility at a glance

Read the row for the tool you already run in production.

Two takeaways from that grid. GramJS reads Telethon-shaped strings, which makes a Node stack cheaper to supply than most buyers assume. And nothing in the list converts upward into a mobile client login, so no purchased format substitutes for having the phone number.

Loading a purchased session in code

Here is the shape of a working Telethon load, with the details that matter left in rather than trimmed for brevity.

from telethon import TelegramClient
from telethon.sessions import StringSession

API_ID = 1234567
API_HASH = "your_api_hash"

with open("acct_001.session.txt") as fh:
    session = StringSession(fh.read().strip())

client = TelegramClient(
    session,
    API_ID,
    API_HASH,
    device_model="Desktop",
    system_version="Windows 10",
    app_version="5.7.1 x64",
    lang_code="en",
    proxy=("socks5", "proxy.host", 1080,
           True, "user", "pass"),
)

with client:
    me = client.get_me()
    print(me.id, me.username, me.phone)

The Pyrogram equivalent is shorter but takes the proxy as a dict.

from pyrogram import Client

app = Client(
    "acct_001",
    session_string=raw_string,
    api_id=API_ID,
    api_hash=API_HASH,
    proxy={"scheme": "socks5",
           "hostname": "proxy.host",
           "port": 1080},
)

with app:
    print(app.get_me())

Run exactly this against two or three sample units before you accept a bulk delivery. A get_me() that returns the expected phone number and user id is the only acceptance test worth trusting, and it takes under a minute per account.

Converting tdata into a session string without burning the auth key

The opentele library handles the conversion. It reads a tdata directory, enumerates the accounts inside, and produces a Telethon or Pyrogram client from the chosen one. The important part is the export flag.

Exporting with the option that reuses the current authorization keeps the desktop auth key and produces a session bound to the same authorized device. Exporting with the option that creates a new session logs in a fresh device using the existing one as authority. Both work. Only the first leaves the account’s active-sessions list unchanged, and on aged inventory that matters, since a suddenly appearing new device is one of the cheapest signals Telegram has.

Three rules keep conversions clean:

1. Close Telegram Desktop, and any anti-detect profile holding the same tdata, before exporting. One auth key used from two live connections gives you AuthKeyDuplicatedError and Telegram invalidates it on both sides.
2. Carry the device metadata across. A session exported from a desktop folder should keep desktop-shaped device_model, system_version and app_version values rather than the library defaults.
3. Convert on a sample of five before you convert 500, and keep the original tdata archives. The tdata is the master copy; the string is a derived artifact you can regenerate.

API ID, API hash and the device fingerprint that ships with them

Your API pair is not a formality. Telegram scores the combination of application identity, device strings and behavior, and inconsistency inside that triple is what separates an account that lives ninety days from one that dies in a week.

Pick one API pair per account family and pin it for the life of those accounts. Store it in the same record as the session so a later worker cannot pair the wrong credentials with the wrong session. Keep the device strings stable too, because an account that reports Windows on Monday and Android on Tuesday from the same auth key is describing an impossible device.

Two anti-patterns account for most avoidable losses. The first is minting a fresh API pair per batch and rotating pairs across the same accounts. The second is leaving library defaults in place, so a hundred accounts all announce the same generic device fingerprint from a hundred different IPs. Fingerprint variation costs nothing to implement and buys real survival time.

Auth failures you will meet in the first hour

Most errors are self-explanatory once you know which layer raised them. These are the ones worth memorizing.

• AuthKeyUnregisteredError — the server does not recognize the key. The session was terminated, the account was banned, or the export is stale. Not recoverable in code; claim a replacement.
• AuthKeyDuplicatedError — the same key connected from two places. Almost always your own concurrency bug, or Telegram Desktop still open on a converted folder.
• SessionPasswordNeededError — two-step verification is on and you have the auth flow but not the cloud password. Request passwords in the delivery file.
• UserDeactivatedBanError — the account is banned. Nothing to debug.
• PhoneNumberBannedError — the number behind it is banned, usually visible immediately on delivery.
• FloodWaitError — you are rate limited, and the exception carries the number of seconds. Sleep it, do not retry through it.
• PeerFloodError — the account has been flagged for unsolicited messaging. Stop sending from that unit and let it rest.
• ApiIdInvalidError — the API id and hash do not form a valid pair. A configuration problem, not an account problem.
• sqlite3.OperationalError: database is locked — two processes on one file session. Move to string sessions.

A healthy delivered batch typically shows 3 to 8 percent hard failures in the first 24 hours across the whole market. Above 15 percent, the problem is the supplier rather than your loader. Our notes on spotting an unreliable PVA seller cover the sourcing side of that.

Proxy binding belongs in the client, not the operating system

Pass the proxy into the client constructor for every account, every time. System-level proxying and VPN tunnels look equivalent in a smoke test and are not, because they route all your clients through one exit. Telegram’s cluster analysis links accounts by exit IP faster than by any behavioral signal, and a shared exit turns individual bans into batch bans.

Budget one residential proxy per account at roughly $5 to $10 per month, geo-matched to the account origin. Buying USA tdata and running it through a Southeast Asian exit throws away the geo premium you paid for. Two or three accounts behind one address is survivable in practice; fifty automated accounts behind one address is a scheduled outage.

Flood limits your library will not enforce for you

Neither Telethon nor Pyrogram rate limits you by default. They will happily fire requests until Telegram pushes back, and by then the account has a mark on it. Build the ceilings into your own scheduler.

Working numbers for automated accounts: keep unsolicited DMs under 30 per account per rolling 24 hours, cap group joins around 20 per day and stay well under the 500 total dialog limit, and put a randomized delay of 3 to 10 seconds between actions rather than a fixed interval. Fresh accounts deserve half those numbers for their first week.

Handle FloodWaitError by respecting the wait value and marking the account cool, not by rotating the same request onto a second account. A pattern of identical requests arriving from different accounts the moment one gets limited is exactly the correlation signal that costs you the whole pool.

Writing a purchase spec a supplier can fulfil exactly

Developer orders go wrong on ambiguity more often than on quality. Nine lines remove most of it:

1. Format, named precisely — tdata folder, Telethon string, or Pyrogram string.
2. Quantity and the delivery structure you want, usually one zip per account plus a CSV index.
3. Geo, and whether it must match the phone origin or only the IP used during creation.
4. Age tier and whether creation dates need to be verifiable.
5. Two-step verification passwords included, or explicitly not set.
6. tdata local passcode included where one exists.
7. Whether the API pair used during creation can be supplied with the batch.
8. Username and profile photo requirements, if the accounts must look established.
9. The replacement window and what counts as a valid claim.

Send that identical text to two or three suppliers and the quotes become comparable. The broader sample-then-scale sequence is in our safe purchasing walkthrough, and if you are still shortlisting vendors, our rated list of bulk Telegram sources covers who actually ships.

MixAcc Telegram formats and pricing

We ship tdata and session strings at the same unit price, because the format is an export step rather than a different product. Name Telethon or Pyrogram in the brief and the strings arrive packed for that library, tested with a get_me() call before dispatch.

Volume rates are quoted per order rather than published as a fixed ladder; send the quantity on Telegram and a price comes back. Every order includes two-step passwords and any tdata local passcode in the delivery file, plus a CSV mapping account index to phone, user id, datacenter and format. Delivery is same-day on most orders, with a 7-day replacement guarantee covering the failure classes listed above. We take crypto and card.

Current tiers and stock sit on the Telegram accounts page. Send a spec covering format, library, quantity, geo and age tier, and a quote comes back with a ship date. Telegram @nexkyc, WhatsApp +1 (737) 307-6751, or allmixacc@gmail.com.