The short answer
- 1If a bot can do it, use the Bot API; most projects stop there.
- 2Building your own Telegram app with a user account means TDLib; raw MTProto is a last resort.
- 3Delivering login codes through Telegram instead of SMS is the separate, paid Gateway API.
In this article
Four ways in, sorted by which account acts
Telegram offers developers four routes, and the names are easy to mix up. The quickest way to tell them apart is to ask which kind of account your code acts as.
| API | Acts as · what you need | Use it for |
|---|---|---|
| Bot API | A bot account · a token from @BotFather | Notifications, customer replies, group tools, mini apps |
| TDLib | A user account · api_id, api_hash and a phone number login | Building your own Telegram app (a client) |
| Telegram API | User or bot accounts · api_id and api_hash | Working with MTProto directly, when there is a clear reason TDLib won't do |
| Gateway API | No chat account · a Gateway account with prepaid funds | Sending sign-up and login verification codes through Telegram instead of SMS |
- Bot API is a plain HTTPS interface. Telegram's servers handle the encryption and the connection to Telegram for you.
- TDLib is Telegram's own client library. It takes care of networking, encryption and local storage, and can be used from any language that can call C functions; Java and .NET bindings are included.
- The Telegram API is the same API the official apps use. You work with hundreds of methods on top of the MTProto protocol yourself.
- The Gateway API is not a messaging tool at all. It is a paid service that delivers verification codes for your own product to your users' Telegram accounts.
Choosing, in order
- Can a bot do it? Replying after a person writes first, sending notifications, showing buttons and opening mini apps are all Bot API work. Most projects stop here; start with creating a bot with BotFather and your first Bot API requests.
- Do you need what a person sees? If your app shows a chat list, contacts and message history, use TDLib; see building TDLib.
- Is TDLib really unsuitable? Only then work with MTProto yourself, and accept that encryption, retries and message ordering are your responsibility; see MTProto at a glance.
- Do you only need to deliver login codes? That is the Gateway API; see the Telegram Gateway API.
Bot accounts and user accounts are different on purpose
| Bot account (Bot API) | User account (TDLib, Telegram API) | |
|---|---|---|
| Start a conversation | No; a person must start the bot first | Yes |
| Phone number | Not needed | Needed to log in |
| Group messages | By default only commands and replies to the bot (privacy mode) | Every message in groups it has joined |
| Created at | @BotFather | my.telegram.org, API development tools |
A bot that cannot message people first is not an inconvenience to work around. It is the anti-spam design. That is why doing bot work with an automated user account gets accounts into trouble; see bot accounts vs user-account automation.
FAQ
What is the difference between the Bot API and the Telegram API?
The Bot API is an HTTPS interface for bot accounts. The Telegram API is the MTProto API the official apps use, for user or bot accounts, and needs api_id and api_hash.
When should I use TDLib?
When you are building your own Telegram client for a user account. TDLib handles networking, encryption and storage for you.
What is the Telegram Gateway API for?
Sending sign-up and login verification codes for your own service to users through Telegram instead of SMS. It is a paid service.
Sources
At a glance
- 1Bot API
Bot account, HTTPS, token from @BotFather.
- 2TDLib / API
User account, api_id and api_hash, phone login.
- 3Gateway
Paid verification codes, no chat account.
Updated
