Telegram APIs

We offer two kinds of APIs for developers. The Bot API allows you to easily create programs that use Telegram messages for an interface. The Telegram API and TDLib allow you to build your own customized Telegram clients. You are welcome to use both APIs free of charge.

You can also add Telegram Widgets to your website.

Designers are welcome to create Animated Stickers or Custom Themes for Telegram.


This API allows you to connect bots to our system. Telegram Bots are special accounts that do not require an additional phone number to set up. These accounts serve as an interface for code running somewhere on your server.

To use this, you don't need to know anything about how our MTProto encryption protocol works — our intermediary server will handle all encryption and communication with the Telegram API for you. You communicate with this server via a simple HTTPS-interface that offers a simplified version of the Telegram API.

Learn more about the Bot API here »

Bot developers can also make use of our Payments API to accept payments from Telegram users around the world.

TDLib – build your own Telegram

Even if you're looking for maximum customization, you don't have to create your app from scratch. Try our Telegram Database Library (or simply TDLib), a tool for third-party developers that makes it easy to build fast, secure and feature-rich Telegram apps.

TDLib takes care of all network implementation details, encryption and local data storage, so that you can dedicate more time to design, responsive interfaces and beautiful animations.

TDLib supports all Telegram features and makes developing Telegram apps a breeze on any platform. It can be used on Android, iOS, Windows, macOS, Linux and virtually any other system. The library is open source and compatible with virtually any programming language.

Learn more about TDLib here »

Telegram API

This API allows you to build your own customized Telegram clients. It is 100% open for all developers who wish to create Telegram applications on our platform. Feel free to study the open source code of existing Telegram applications for examples of how things work here. Don't forget to register your application in our system.

Getting started

Creating an application

How to get your application identifier and create a new Telegram app.

User authorization

How to register a user's phone to start using the API.

Two-factor authentication

How to login to a user's account if they have enabled 2FA, how to change password.

QR code login

QR code login flow

Error handling

How to handle API return errors correctly.

Handling different data centers

How to connect to the closest DC access point for faster interaction with the API, and things to watch out for when developing a client.

Handling updates

How to subscribe to updates and handle them properly.

Handling PUSH-notifications

How to subscribe and handle them properly.

Channels, supergroups and groups

How to handle channels, supergroups, groups, and what's the difference between them.

Channel statistics

Telegram offers detailed channel statistics for channels with more than 500 subscribers.

Calling methods

Additional options for calling methods.

Uploading and Downloading Files

How to transfer large data batches correctly.


How to fetch results from large lists of objects.

Client configuration

The MTProto API has multiple client configuration parameters that can be fetched with the appropriate methods.


Secret chats, end-to-end encryption

End-to-end-encrypted messaging.

Security guidelines

Important checks required in your client application.

Perfect Forward Secrecy

Binding temporary authorization key to permanent ones.

End-to-End Encryption in Voice and Video Calls

End-to-end-encrypted calls.


Client optimization

Ways to boost API interactions.

API methods

Available method list

A list of available high-level methods.

API TL-schema, as JSON

Text and JSON-presentation of types and methods used in API.

Available layer list

A list of available schema versions.

Other articles

Admin, banned and default rights for channels, supergroups and groups

How to handle admin permissions, granular bans and global permissions in channels, groups and supergroups.

Min constructors

Sometimes, user and channel constructors met in group chat updates may not contain full info about the user: how to handle such constructors.

Account deletion

How to reset an account if the 2FA password was forgotten.

Telegram Passport

How to work with Telegram Passport directly using the MTProto API.

Telegram Payments

How to work with Telegram Payments directly using the MTProto API.

Styled text with message entities

How to create styled text with message entities

Working with animated emojis

Graphical telegram clients should transform emojis into their respective animated version.

Working with animated dice

Telegram supports sending animated dice emojis.

Message drafts

How to handle message drafts


Working with folders

Top peer rating

If enabled, the rating of top peers indicates the relevance of a frequently used peer in a certain category (frequently messaged users, frequently used bots, inline bots, frequently visited channels and so on).

Handling file references

How to handle file references.

Seamless Telegram Login

Handle Seamless Telegram Login URL authorization requests.

Web events

When interacting with HTML5 games and the websites of payment gateways, Telegram apps should expose the following JS APIs.