LinkedIn
Instagram
WhatsApp
Telegrama
Gmail
Perspectivas
Google Agenda
Participe da comunidade do Slack Índice
The two models
Capabilities & cost
Telegram Bot API vs Telegram API
Telegram Bot API vs Telegram API: Which One Do You Need?
O API do bot do Telegram e o API do Telegram (also called the Telegram User API, built on MTProto) solve different problems. One runs a bot account over HTTP. The other runs a real user account over a binary protocol you implement yourself. This guide breaks down where each one blocks you, endpoint by endpoint, and what it actually costs to build and maintain a Telegram User API client versus connecting an existing account through Unipile.
// Bot API: blocked, the user never messaged the bot
const res = await bot.sendMessage(userId, "Hi there");
// -> 403 Forbidden: bot was blocked by the user
// or never started a conversation
// Telegram User API via Unipile: works, it is a real account
// POST /v2/:account_id/chats/send
const chat = await unipilar.bate-papos.create({
account_id: telegramAccountId,
user_ids: [username],
text: "Hi there"
});chat.status: "sent"
The two models
Telegram Bot API vs Telegram User API, in one table
If you already know that Telegram has multiple APIs and you just want to know which one applies to your project, this table gets you there in ten seconds. If you still need the full picture of all three Telegram APIs, read the getting-started guide first. Here, we go one level deeper on the two that people actually build against: the Bot API and the Telegram User API.
| Critérios | API do bot do Telegram | Telegram User API (MTProto) |
|---|---|---|
| What it connects | A bot account, created and owned by your app | A real Telegram user account, phone-number bound |
| Protocolo | Standard HTTP, JSON requests and responses | MTProto, a custom binary protocol you implement |
| Credenciais | A bot token issued by @BotFather | api_id + api_hash from my.telegram.org |
| Identity in chats | Shows a visible "bot" badge, distinct from a person | Indistinguishable from a person using the app |
| Who can message whom | Bot can only reply once a user starts the chat | Account can message anyone, like any Telegram user |
| Typical implementation | Any HTTP client, official and community SDKs | Telethon, Pyrogram, GramJS, TDLib, or a linked account via Unipile |
| Custo | Free to use | Free to use, self-hosted infrastructure cost only |
API do bot do Telegram
ConnectsA bot account
ProtocoloHTTP, JSON
CredenciaisBot token (BotFather)
IdentityVisible bot badge
Who it can messageOnly users who messaged first
CustoGrátis
Telegram User API (MTProto)
ConnectsA real user account
ProtocoloMTProto, binary
Credenciaisapi_id + api_hash
IdentityIndistinguishable from a person
Who it can messageAnyone, like a normal user
CustoFree, self-hosted cost only
The question that decides
Who do you want to write to first?
Every other difference between the Telegram Bot API and the Telegram User API is secondary to this one. Answer it first and the rest of this guide becomes a checklist, not a decision.
A bot cannot start a conversation with a user who has never messaged it first
This is a Telegram platform rule, not a Unipile limitation or a library bug. A bot account can only reply inside a chat the user already opened, or after the user taps a
This is a Telegram platform rule, not a Unipile limitation or a library bug. A bot account can only reply inside a chat the user already opened, or after the user taps a
t.me deep link or joins a group the bot is in. If your use case requires reaching out to someone who has not interacted with your bot yet, the Bot API is not an option, no matter which framework or library sits on top of it. Bot API works
The user talks to your bot first
Support bots, command-driven tools, notification opt-ins, chatbots linked from your product. The user finds your bot, starts the chat, and everything from there onward is a normal exchange the Bot API handles well. Bot API blocked
You need to reach out first
Sales outreach, recruiting, customer messaging tied to an existing contact list, or any workflow where your product initiates contact with a Telegram user. This requires a real user account, which means the Telegram User API (MTProto), not the Bot API.Capability matrix
What actually works, endpoint by endpoint
Beyond the headline difference, here is where each option blocks you in practice. "Telegram User API (raw)" means a self-built MTProto client with a library such as Telethon, Pyrogram, GramJS or TDLib. "Unipile" means the same real user account, connected without writing MTProto code yourself.
| Capacidade | Bot API | Telegram User API (raw) | Unipile |
|---|---|---|---|
| Start a chat with a user who never messaged first | Não | Yes, subject to the user's privacy settings | Yes, same rule as any Telegram account |
| Send and receive text messages | Yes, in chats the bot is part of | Sim | Sim |
| Read message history from before the bot joined | Não | Sim | Sim |
| Group participant list, add, remove | Limited to the bot's own permissions | Yes, if you build it | Yes, getParticipantsList, addParticipant, removeParticipant |
| Group administration: approve, promote, revoke | Yes, only if the bot is an admin | Yes, if you build it | Não suportado |
| Channels, communities, broadcasts | Yes, if added as admin | Sim | Não suportado |
| Secret chats | Não se aplica | Yes, if you build it | Não suportado |
| Contact, location, poll, event attachments | Sim | Sim | Não suportado |
| Chamadas de voz e vídeo | Não | Possible, high implementation effort | Não suportado |
| Chat theme, archiving, chat deletion | Não se aplica | Yes, if you build it | Não suportado |
| Account identity | Separate bot identity, visible badge | Real user identity, phone-number bound | Real user identity, your existing account |
| Session and device management | Token-based, no device concept | You manage the MTProto auth key and 2FA yourself | Managed via Telegram's own Devices feature |
Start a chat cold
Bot APINão
User API (raw)Yes, privacy-dependent
UnipileSim
Message history before joining
Bot APINão
User API (raw)Sim
UnipileSim
Group participants (get / add / remove)
Bot APILimited to bot permissions
User API (raw)Yes, self-built
UnipileYes, dedicated endpoints
Group administration
Bot APIYes, if admin bot
User API (raw)Yes, self-built
UnipileNão suportado
Channels, communities, broadcasts
Bot APIYes, as admin
User API (raw)Sim
UnipileNão suportado
Secret chats
Bot APINão se aplica
User API (raw)Yes, self-built
UnipileNão suportado
Contact / location / poll / event attachments
Bot APISim
User API (raw)Sim
UnipileNão suportado
Chamadas de voz e vídeo
Bot APINão
User API (raw)Possible, high effort
UnipileNão suportado
Session / device management
Bot APIToken-based
User API (raw)Self-managed auth key + 2FA
UnipileTelegram's own Devices feature
What Unipile does not cover on Telegram
Channels, communities and broadcasts, chat theme, secret chats, contact, location, poll and event attachments, group administration (approving, promoting, revoking), chat deletion, archiving, and voice or video calls. If your project needs any of these, only a self-built Telegram User API client covers the full surface.
Channels, communities and broadcasts, chat theme, secret chats, contact, location, poll and event attachments, group administration (approving, promoting, revoking), chat deletion, archiving, and voice or video calls. If your project needs any of these, only a self-built Telegram User API client covers the full surface.
The real cost
The real cost of building on MTProto
The Telegram User API is free of charge, but "free" only covers the license. Building and maintaining a Telegram User API client yourself has a real engineering cost that a Bot API integration never has. Here is what that cost actually looks like.
01
Session and auth key management
MTProto is a binary protocol, not REST. You implement the TL schema, the auth key exchange, and persist the resulting session yourself. Lose the session and the user has to re-authenticate from scratch. 02
Two-factor authentication
Accounts with a cloud password require handling Telegram's SRP-based 2FA flow during login. It is one more state machine to build, test, and keep working across every Telegram protocol update. 03
One api_id per phone number
api_id e api_hash are issued on my.telegram.org under "API development tools," and require an active Telegram account. Telegram allows a single api_id per phone number, which shapes how you provision test and production credentials. 04
Accounts under automatic observation
Unofficial clients are placed under automatic observation by Telegram. Flooding, spam, and artificially inflating counters can trigger a permanent ban, which means rate limiting and warm-up are your responsibility, not a library default.// Copy-pasting a sample api_id from an open source repo
// instead of registering your own on my.telegram.org
Error: API_ID_PUBLISHED_FLOOD
// Telegram flags api_id values published in public code.
// Every application you ship needs its own api_id / api_hash,
// one per phone number, or your end users hit this error.The third way
Connect an existing account, skip the MTProto build
Most teams do not actually want to build a Telegram client. They want the capabilities of a real user account: starting conversations, reading full history, managing group participants, without owning a binary protocol implementation. That is what Unipile's API do Telegram is for.
Connect via Telegram's own Devices feature
Unipile links an existing Telegram user account through Telegram's Devices function, the same mechanism that lets you log into Telegram Desktop or Telegram Web. Login happens by QR code, or through Hosted Auth with
Unipile links an existing Telegram user account through Telegram's Devices function, the same mechanism that lets you log into Telegram Desktop or Telegram Web. Login happens by QR code, or through Hosted Auth with
providers: "TELEGRAM" for a drop-in connection flow. No api_id, no api_hash, no MTProto to write
You never handle the auth key exchange, the TL schema, or 2FA yourself. The linked account behaves like a real Telegram user because it is one, not a bot and not a simulated client.
You never handle the auth key exchange, the TL schema, or 2FA yourself. The linked account behaves like a real Telegram user because it is one, not a bot and not a simulated client.
Group participants, through dedicated endpoints
getParticipantsList, addParticipant, removeParticipant, exposed via POST, OBTERe DELETE /v2/{account_id}/chats/{chat_id}/participants. No custom MTProto calls to write for basic membership management. Session status tied to Telegram's device list
If the Unipile device is removed from the account's active sessions inside Telegram, the account status switches to
If the Unipile device is removed from the account's active sessions inside Telegram, the account status switches to
disconnected. Session lifecycle is visible and predictable, not a black box you debug alone. // Connect an existing Telegram user account
// via Hosted Auth, no MTProto code required
const link = await unipilar.hostedAuth.create({
providers: ["TELEGRAMA"],
expiraEm: "2026-12-31T23:59:59.000Z"
});
// User scans the QR code with the Telegram app
// Account status becomes "connected"
// GET /v2/{account_id}/chats/{chat_id}/participants
const members = await unipilar.bate-papos.getParticipantsList(chatId);account.status: "connected"
Same rules, no shortcut around them
A linked account is still a Telegram account and follows Telegram's own limits: avoid brand new accounts for heavy use, ramp up volume progressively, and keep at least 10 to 20 seconds between messages. See the Telegram API guide e o send message guide for the full setup.
A linked account is still a Telegram account and follows Telegram's own limits: avoid brand new accounts for heavy use, ramp up volume progressively, and keep at least 10 to 20 seconds between messages. See the Telegram API guide e o send message guide for the full setup.
Decision tree
Which one is right for your case
Three questions, in order. Stop at the first one that matches your project.
1
Does the user always message you first, and does the bot only need to reply to commands and messages?
->Support bots, opt-in notifications, command tools where the user initiates contact.Bot API
2
Do you need to reach out first, and do you also need channels, secret chats, group administration, or calls?
->Full platform coverage, and you are willing to build and maintain your own MTProto client with Telethon, Pyrogram, GramJS or TDLib.Telegram User API, self-built
3
Do you need to reach out first, act as a real account, and get moving without owning MTProto?
->Messaging, chat history, and group participant management on a connected user account, with the session handled for you.Unipile
Most teams land here
Connect a real Telegram account without building a client
If your project needs to reach out first but does not need channels, secret chats, or calls, a linked account through Unipile gets you there without a Telegram User API implementation to maintain.
Construa com Unipile Connect a real Telegram account without building a client
If your project needs to reach out first but does not need channels, secret chats, or calls, a linked account through Unipile gets you there without a Telegram User API implementation to maintain.
Telegram Bot API vs Telegram API - FAQ
Common questions on choosing between the Telegram Bot API and the Telegram User API (MTProto).
The Bot API is an HTTP interface that drives a bot account and exposes a deliberately limited surface. The Telegram API, also called the Client API, speaks the MTProto binary protocol and drives a real user account with the full feature set. They are different account types, not two versions of the same thing.
Ask who you need to write to. If your users message you first and a bot identity is acceptable, use the Bot API. If you need to reach people who have not contacted you, or to act as a real person, you need user-account access.
No. The user must start the conversation first. This is the single limit that pushes most products off the Bot API, and no endpoint works around it.
No. The Bot API only needs the bot token that BotFather gives you. api_id and api_hash come from my.telegram.org and are for the Client API, with one api_id allowed per phone number.
Hard enough that almost nobody writes it from scratch. You handle session persistence, two-factor authentication, reconnection and a binary protocol. Most teams use Telethon, Pyrogram, GramJS or TDLib, and still own the session lifecycle.
It is another name for the Client API, the MTProto interface that authenticates as a real Telegram user rather than a bot.
Yes. Connecting an existing account through Telegram's Devices feature gives user-account access without implementing MTProto. That is how Unipile links Telegram accounts, through a QR code login or a hosted authentication flow.
Ainda tem dúvidas? Nossa equipe está aqui para ajudar.
BR 
EN 
FR 
ES 
DE 
IT 
NL 
PL 
TR