Telegram Bot API vs User Accounts: TDLib and MTProto

api What the client library actually is

Underneath every Telegram application is a binary protocol, and speaking it involves serialisation, session handling, key exchange and encryption. Nobody sensible implements that from scratch; Telegram publishes an official library that does it, exposing an interface any language can call.

What you get is genuinely substantial: a maintained implementation of the protocol, a local encrypted database that keeps the account's state on disk, synchronisation that recovers from dropped connections, and access to everything a user account can do rather than the subset bots may do.

What you also get, and should say out loud before building anything: a full local copy of that account's data, on your server. Messages, files, contacts, group memberships. That is not a side effect to be managed later; it is the thing you have built, and it changes what your hosting is, who may access it, and what a compromise of it means.

And the login it creates is a session on that account — visible in the device list from Step 028, revocable from a phone, and capable of doing everything a signed-in device can. If the account belongs to somebody else, you are asking them for that, and they should understand what they are agreeing to.

gavel The line, stated plainly

The library is official and legitimate. Some of the things people build with it are not, and the boundary is not subtle once named.

Reasonable uses. Building a client application — an alternative interface, an accessible client, something for a device nobody has written an app for. Archiving or exporting your own account, where the bot interface simply cannot reach your history. Administrative operations on communities you run that bots are not permitted to perform. A desktop tool you use yourself. In each of these the account involved is yours and the behaviour is a person's.

Uses that get accounts limited. Collecting member lists from groups. Messaging people who never contacted you. Joining channels automatically at scale. Running an account that posts, reacts or replies on a schedule as though it were a person. Operating several accounts from one system to simulate activity.

These are not grey areas, and the enforcement is not theoretical — it is the direct cause of the restrictions described in Step 037. The consequence lands on the account, which usually means a real person's number, contacts and chat history, and it arrives without warning or appeal.

alt_route What people actually wanted

Most projects that reach for a client library were solving a problem the bot interface solves differently. Four recurring ones:

"The bot cannot read the group's messages." It can, if privacy mode is off or it is an administrator — Step 086. The default is a restriction that can be changed, not a wall.

"I need to know who is in the group." A bot with the right permission can see the member list of a group it administers. What it cannot do is harvest members of communities you do not run, which is the case the restriction exists for.

"The file is too large." There are size limits on the bot interface, and for genuinely large files the honest answers are hosting the file somewhere and sending a link, or splitting it — both of which are better for the recipient than a multi-gigabyte transfer they did not ask for.

"I want to export everything." The applications have a built-in export, covered in Step 048, which produces a complete archive without anybody writing code. It is almost always what "I need MTProto to archive my chats" turns out to mean.

Working through these four honestly removes the requirement in most cases. When it does not — and there are real cases — you now know that you are building a client rather than working around a bot.

touch_app Try it now — five minutes

Four steps. The first two will end the question for most readers.

1. Write down the capability you think you need One sentence. Then check it against the four cases above before assuming the bot interface cannot do it.
2. If it still stands, name the account Not "an account" — a specific one, belonging to a specific person, with a specific history on it.
3. Open your device list Look at what a signed-in session is, from the account's side. That is what your program will appear as.
4. Decide where the local database lives If you proceed, the answer is a disk holding somebody's messages. Encrypt it, restrict it, and back it up deliberately or not at all.

construction If you do build one

Four operational realities that are rarely in the tutorial.

State lives on disk, and it matters. The library keeps a database that represents the account, and deleting it is not a clean restart — it means a fresh synchronisation and, in some cases, a fresh login. Treat that directory as the important part of your deployment, not as a cache.

Logging in is interactive the first time. Somebody types a code, and possibly a password. That does not fit a deployment pipeline, so decide early how a first run and a re-authentication happen, because the answer "somebody logs into the server" is the one you will end up with by accident.

Rate limits still exist, and are stricter in spirit. Acting like a person means being expected to behave like one. Bursts of activity that a bot would merely be throttled for look, on a user account, like exactly what the restrictions are for.

Secret chats are the one thing to leave alone. They are tied to a device by design, and a system that synchronises an account's content is at odds with the reason those conversations exist. If an account has them, be clear with its owner about what your tool does and does not touch.

switch_account The dedicated account, and why it is not a shield

The usual response to everything above is to create a separate account to run the automation on, so that a personal one is never at risk. It is a sensible instinct and it does less than people expect.

It does not make the behaviour permitted. The rules describe what accounts may do, not which account is doing it, so a purpose-made account running the same activity is limited on the same terms — often faster, because a new account with no history behaving mechanically is the easiest pattern there is to spot.

It still needs a real number, which means a real phone line or one of the arrangements from Step 090, with everything that implies about custody and recovery. Accounts do not come from nowhere.

And whatever it owns, it takes with it. This is the expensive part. If the dedicated account is the creator or owner of a group or channel, a limitation on that account is a problem for the community rather than for the script — ownership, administrator rights and the ability to recover the room all sit behind an identity you have just put at risk.

If you use one regardless, the discipline is simple: it owns nothing. It is a member with the rights it needs, in rooms owned by a person, and losing it costs you a rebuild rather than a community.

help Common questions at this stage