Telegram Bot API vs MTProto vs Userbots: What's the Difference?

MTProto is the protocol every Telegram app uses to talk to Telegram's servers, and the Telegram API built on it lets developers write full Telegram clients. The Bot API is a simpler web interface, run by Telegram, that lets you control a bot account with ordinary HTTPS requests. A userbot is a normal user account controlled by a program through the MTProto API instead of by a person tapping buttons. Bots are the supported way to automate things for other people; userbots are possible but carry account risks and strict rules.

This guide explains the three in plain language: how they fit together, what each can and cannot do, which limits apply, what Telegram's rules say, and how to choose for a given project. It describes concepts and methods in words, with no code. For hands-on setup, see our guides to creating a bot with BotFather and getting your API ID and API hash.

The short version

• MTProto is a protocol, a set of rules for encrypting and exchanging data between apps and Telegram's servers. You do not choose it against the others; it is underneath everything.
• The Telegram API (often called the MTProto API or client API) is the full set of methods official and third-party apps use. It works for user accounts and bot accounts. You need an API ID and API hash from Telegram to use it.
• The Bot API is a separate, simplified service. You send HTTPS requests with a bot token to Telegram's Bot API server, which talks MTProto to Telegram on your behalf.
• A userbot is not a separate technology. It is a user account logged in through the client API by a program, so the program can act as that person.

How the layers fit together

Picture three layers.

1. Telegram's servers store messages, accounts and chats.
2. MTProto is the encrypted language spoken between the servers and anything that connects to them.
3. Clients connect using MTProto: the official apps on Android, iPhone and desktop, Telegram Web, third-party apps, and programs built with the client API.

The Bot API sits to the side. Telegram runs a Bot API server that is itself an MTProto client. Your bot sends simple web requests to that server, such as "send this message to this chat", and the server turns them into MTProto calls. Updates flow back the other way: the Bot API server receives them over MTProto and hands them to your bot by long polling or webhook. Our guide on setting a webhook explains those two delivery methods.

Telegram has published the Bot API server's source code, so you can also run your own copy, called a local Bot API server. It speaks the same simple interface, but runs on your machine and lifts some limits, covered below.

MTProto: the protocol

MTProto is Telegram's own protocol. It handles encryption between the app and the server, how messages are packaged, how sessions are kept alive across network changes, and how data is split across Telegram's data centres. Secret chats use an end-to-end layer on top of it; normal cloud chats are encrypted between the app and the server. Our guide on whether Telegram is end-to-end encrypted explains that difference.

Most developers never touch MTProto directly. They use a library that implements it. Telegram maintains an official one, TDLib (Telegram Database Library), which handles the protocol, local storage and updates, and many official and third-party apps are built on it. Community libraries exist for many programming languages as well.

When people say "use MTProto" in a bot or automation discussion, they usually mean "use the client API through one of these libraries" rather than the Bot API.

The client API: what full access means

The client API is the complete interface. Everything the official apps can do, they do through it: sending and reading messages, managing contacts, joining chats, uploading and downloading files, changing settings, viewing statistics, and much more.

What you need

1. An API ID and API hash, which identify your application. You get them by signing in to Telegram's developer site with a phone number. Telegram's documentation ties each API ID to the account that created it, and says the sample IDs used in examples are limited and unsuitable for apps released to the public.
2. An account to log in with. That is either a user account, which logs in with a phone number and login code, or a bot account, which logs in with a bot token.
3. A library that implements MTProto, such as TDLib.

Who uses it

• Developers of alternative Telegram apps. Our guide to third-party Telegram clients covers that side.
• Tools that need features the Bot API does not offer, such as reading a chat's full history as a user or downloading very large files.
• Bots that want more control than the Bot API gives. A bot account can log in through the client API with its token, though it is still a bot and keeps bot restrictions.

What it costs you

The client API is more complex. You manage sessions, local storage, data centres, flood-wait errors and updates. A session file or session string is effectively a logged-in device; anyone who copies it can act as that account. It must be protected like a password.

The Bot API: what bots are for

The Bot API exists to make bots easy to build. A bot is a special Telegram account, created through @BotFather, that is clearly marked as a bot and controlled by software. Our explainer on what Telegram bots are gives the user's view.

What the Bot API offers

• Simple requests. Each action is a web request with a method name and parameters, such as sendMessage with a chat ID and text.
• Bot-only features. Inline keyboards and reply keyboards, inline mode, commands with menus, payments with providers and Telegram Stars, games, Mini Apps, and business-account connections. See our guides on inline bots, Mini Apps and bot payments for developers.
• Webhooks. Telegram can push updates to your server.
• No phone number. A bot does not need a SIM card; it is created in a chat with @BotFather.
• Clear identity. Users can see they are talking to a bot.

What bots cannot do

These limits are deliberate, and they are what make bots safe to allow on a large scale.

• A bot cannot start a conversation. It can only message a user who has started it first, and it cannot message users who have blocked it.
• A bot cannot read your private chats with anyone else. It only sees messages sent to it, or messages in groups and channels where it is a member.
• In groups, privacy mode is on by default. A bot in privacy mode sees commands and replies addressed to it, but not every message, unless it is an admin or privacy mode is turned off in @BotFather.
• A bot cannot fetch old history through the Bot API. It sees updates from the moment it receives them, not the earlier messages of a chat.
• Bots cannot add themselves to chats, and they cannot see who is in your contacts.

File size limits

Telegram's Bot API documentation states that through the standard cloud Bot API, bots can download files up to 20 MB and upload files up to 50 MB. With a local Bot API server, the documentation says uploads of up to 2000 MB are possible and downloads have no size limit. Telegram notes these limits may change, so check the current documentation before designing around them.

Rate limits

The Bot API limits how fast a bot can send, especially many messages to many users or many messages to one group. Telegram's bot FAQ gives guidance on safe rates. Exceeding them returns an error asking the bot to wait a number of seconds. Our guide on flood wait explains how to handle these. User accounts have limits too, and they are not published as precise numbers. A client-API program that sends, joins or looks up users faster than a person would will meet flood waits, and repeated pressure can lead to longer restrictions. The safest design for both layers is the same: queue actions, spread them out, and treat every wait request as an instruction rather than an obstacle.

For mass notifications, see our guide on sending broadcast messages to bot subscribers.

Userbots: a person's account run by a program

A userbot logs in to a normal user account through the client API and acts automatically. Technically, it can do anything the account owner could do in the app: read chats, reply, forward, join groups, react, download media.

Legitimate uses

People use their own accounts with automation for personal tasks such as:

• Saving copies of their own messages or media from chats they are in.
• Personal shortcuts, like auto-formatting their own messages.
• Research on public channels they follow, within Telegram's rules.
• Exporting their own data. Telegram's own apps also offer an export feature; see our guide on exporting chat history.

Why userbots are risky

• Telegram watches unusual activity. Telegram's developer documentation says accounts that log in through unofficial API clients are automatically put under observation, and that flooding, spamming or faking subscriber and view counts can lead to a permanent ban.
• Spam rules apply fully. Telegram's terms forbid spam and scams. An account that sends unsolicited messages, joins many groups quickly or posts the same message everywhere will be limited or banned. People reporting it as spam can restrict it from contacting strangers. Our guide on banned Telegram accounts covers what happens next.
• Your session is a key. If the program, server or library is compromised, the attacker gets your account, including all your chats.
• Others' privacy. A userbot sees everything the account sees, including other people's messages in private chats and groups. Collecting or reusing that data can breach their privacy and laws in your country.
• Bought accounts are worse. Accounts sold in bulk are often flagged quickly, and using them to message strangers is exactly what Telegram's anti-spam systems are built to catch.

What userbots must never be used for

• Cold-messaging people who did not ask to hear from you.
• Mass-adding people to groups or channels.
• Inflating views, reactions or subscriber counts. Our guide on why bought subscribers hurt explains the damage.
• Scraping members of groups to target them.
• Monitoring or tracking individuals.

If a project needs any of these, the honest answer is that it should not be built.

How each one receives new messages

The way updates arrive shapes how you host the software.

Bot API

Telegram's Bot API server keeps incoming updates for your bot until you collect them, for a limited time. You collect them in one of two ways:

• Long polling: your program repeatedly asks for new updates, and each request waits briefly if nothing is there yet. It works from any machine, even one behind a home router.
• Webhook: you give Telegram an HTTPS address, and each update is sent there as it happens. It needs a public server but no constantly running loop.

Because each update is a separate web request, a webhook-based bot can run on serverless hosting that starts only when a message arrives. That keeps small bots cheap and simple.

Client API

A client keeps a connection open to Telegram and receives updates pushed over it. When it reconnects after being offline, it asks Telegram for the difference since its last known state and catches up. That means a client-API program usually runs as a long-lived process on a server or computer that stays on. It cannot easily sleep between messages the way a webhook bot can.

This difference alone often decides the question. If you want something light that wakes up on demand, the Bot API fits. If you need a constantly connected account, you are in client-API territory, with the hosting that implies.

Identifiers: why the same chat looks different

Developers moving between the two interfaces are often confused by IDs.

• In the Bot API, every user, group and channel is addressed by a single numeric chat ID. Channels and supergroups have IDs that look different from user IDs, but you can store any of them as one number and send to it. Public chats can also be addressed by their username. Our guide on getting a chat ID or channel ID explains how to find them.
• In the client API, addressing many users and channels needs both an ID and an access hash, a value the client learns when it first sees that user or chat. Without it, the client cannot simply message an ID it found somewhere else. This is a deliberate protection: you can only reach peers your account has legitimately encountered.
• Files have their own identifiers in both. In the Bot API, a file ID lets a bot send the same file again without re-uploading it. File IDs from one bot are not meant to be used by another.

Running in groups and channels

Most real bots work inside groups and channels, so it helps to know what each layer can do there.

• A bot must be added by an admin. For a channel, it needs to be an admin to post. In groups, its admin rights decide whether it can delete messages, restrict members, pin and so on. Our guide on adding a bot to a channel or group walks through it.
• Give the minimum rights. A posting bot needs to post, not to add admins. Every right you grant is a right a leaked token would grant to someone else.
• A user account in a group has whatever rights that person has. A userbot acting as a group admin can do everything that admin can, which is why admin accounts should never be automated casually.
• Channel statistics, member lists and join requests each have their own rules about who can see them. The client API generally exposes what the logged-in account could see in the app; the Bot API exposes a narrower, bot-specific set.

Testing without touching real users

Telegram provides a separate test environment for developers, with its own accounts and data, distinct from the production service. Both bots and client applications can be pointed at it. Using it means mistakes, floods and half-built features never reach real chats. The details of creating test accounts change from time to time, so follow Telegram's current developer documentation.

Even without the test environment, create a private group with only yourself and a second account, add your bot, and try every feature there before releasing it.

Moving from one approach to another

Projects sometimes start in one layer and outgrow it.

• From a userbot to a bot. Common when a personal tool becomes useful to others. Replace "act as me" features with ones where users start the bot and give it permission. It is more work at first but removes the account risk.
• From the Bot API to the client API with a bot token. Done when a bot needs larger files or methods the Bot API does not expose. The bot keeps its username and users notice nothing, but you take on session management.
• From the cloud Bot API to a local Bot API server. The simplest way to lift file limits while keeping the same interface. You become responsible for hosting it, keeping it updated, and placing it behind HTTPS.

Side-by-side comparison

Identity

• Bot API: a bot account, clearly labelled as a bot.
• Client API with a bot token: still a bot, same label and restrictions.
• Userbot: looks like a normal person.

Setup

• Bot API: create a bot with @BotFather, get a token, send HTTPS requests. Minutes.
• Client API: get an API ID and hash, pick a library, handle login and sessions. Hours to days.
• Userbot: the client API setup plus a phone number and a user login.

Who can be messaged

• Bots: only users who started the bot, and chats the bot was added to.
• Userbots: technically anyone a user could message, but unsolicited messages are spam under Telegram's rules.

Features

• Bots: buttons, inline mode, payments, Stars, games, Mini Apps, webhooks, business connections.
• User accounts: full chat history, contacts, joining chats by themselves, all normal user features, but none of the bot-only interface features.

Files

• Standard Bot API: smaller limits, as above.
• Local Bot API server or client API: much larger files.

Risk

• Bots: low risk if you follow the bot developer terms.
• Userbots: real risk of limits or bans, plus security risk to the account.

How to choose for your project

Answer these questions in order.

1. Is the software meant to serve other people? Customer support, a shop, a community helper, notifications, a game: use a bot and the Bot API. That is what Telegram built them for.
2. Does it need a bot-only feature? Buttons, payments, Stars, Mini Apps, inline mode: only bots have them.
3. Does it need large files? Run a local Bot API server, or use the client API with your bot's token.
4. Does it need to read a chat's earlier history or act as you personally? That is a client-API job. Limit it to your own data and chats you belong to, keep it slow and human-paced, and accept the account risk.
5. Is the plan to reach strangers? Stop. No technical layer makes unsolicited messaging acceptable on Telegram.

Example decisions

These are hypothetical projects.

• A bakery wants order notifications. Bot API. Customers start the bot from the website, and the bot messages them when an order is ready.
• A podcast team wants to post large episode files to its channel automatically. A bot that is an admin of the channel, running through a local Bot API server or the client API with its bot token, to handle the larger files.
• A researcher wants to archive public posts from channels they follow. The client API with their own account, at a gentle pace, keeping to public content, or better, the channels' public web previews and RSS where available. Our guide on Telegram channel RSS feeds covers that route.
• A marketer wants to message every member of a competitor's group. No. That is spam, it breaks Telegram's rules and it will get accounts banned.

Security basics for any of the three

• Bot token: store it in a secret store, never in public code repositories. Revoke and regenerate it through @BotFather if it leaks.
• API ID and hash: treat them as private to your application.
• Session files and strings: they are logged-in devices. Encrypt them, restrict who can read them, and terminate the session from Telegram's active sessions list if you stop using it. Our guide on logging out of all devices shows how.
• Two-step verification on any user account involved. See setting up two-step verification.
• Never share login codes with a tool or person. A tool that asks you to paste your login code into its website is taking over your account.

Misconceptions worth clearing up

"A bot in my group can read my private messages"

No. A bot sees only what is sent to it and, depending on privacy mode and admin rights, messages in the groups it belongs to. It has no access to your private chats with other people. What a bot in a group can see is still worth checking before you add it; our guide on whether Telegram bots are safe covers this.

"A userbot is invisible"

A userbot looks like a person to other users, but Telegram sees the login, the app identity it uses and the pattern of its activity. Automated behaviour, such as replying instantly at all hours or joining many chats quickly, stands out. Being undetectable is not something to plan on, and trying to hide automation from Telegram is exactly what its rules address.

"The Bot API is a lesser, slower version"

The Bot API adds a small hop between your program and Telegram, but for normal bots that is rarely noticeable. Its limits on files and history are design choices, not signs of a weaker product, and it is the only way to get some features, such as Mini Apps and payments, in a simple form.

"You need the client API to post to a channel automatically"

You do not. A bot that is an admin of the channel can publish posts, edit them and pin them through the Bot API. Our guide on auto-posting blog articles to Telegram uses exactly this approach.

Common mistakes

• Building a userbot for a customer-facing service. A bot is safer, supported and has better features.
• Thinking MTProto is an alternative to the Bot API. It is the layer under everything; the real choice is between the Bot API and the client API.
• Using sample API IDs in a released app. They are limited and not meant for production.
• Turning off privacy mode without need. The bot then receives every group message, which means more data to protect and more load.
• Hard-coding a bot token in public code. Tokens leaked this way get abused quickly.
• Ignoring flood waits. Retrying immediately makes limits longer.
• Using bought accounts. They are flagged and banned, and using them to message strangers is spam.

FAQ

Is the Bot API built on MTProto?

Yes. Telegram's Bot API server is an MTProto client that translates your simple HTTPS requests into MTProto calls. You do not deal with MTProto yourself when you use the Bot API.

Can a bot log in through the client API?

Yes. A bot can authenticate to the client API with its token, which gives access to some things the Bot API does not expose, such as larger file handling. It is still a bot and keeps bot restrictions, such as not being able to start conversations.

Are userbots allowed on Telegram?

Telegram lets developers build their own clients with the API, and using your account through such software is not banned in itself. But accounts using unofficial clients are monitored, and spam, flooding or faking counts can lead to a permanent ban. Use them only for your own data and normal, human-paced activity.

Why can't my bot message a user first?

Bots can only message users who have started them. It is one of the core rules that prevents bots from being used for spam. Give users a link to start the bot instead.

What is a local Bot API server?

It is your own copy of the Bot API server, run from Telegram's published source code. Your bot sends requests to it instead of Telegram's public Bot API address, and it allows larger file uploads and downloads.

Which should a beginner learn first?

The Bot API. It is simpler, covers most real projects, and carries little account risk. Move to the client API only when you hit a specific limit.

Summary

MTProto is the protocol beneath every Telegram connection. The client API built on it gives full access for user and bot accounts, at the cost of complexity and session security. The Bot API is a simple, Telegram-run interface for bots, with bot-only features and deliberate limits, such as never messaging users first. A userbot is a person's account driven by software; it is powerful but monitored, risky and never acceptable for unsolicited messaging. For anything that serves other people, choose a bot.