Using the Telegram API

Our API 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.

Error handling

How to handle API return errors correctly.

Handling different data centers

How the nearest data center is selected for faster interaction with the API and things to beware of when developing a client.

Handling updates

How to sign for updates and handle incoming messages.

Handling PUSH-notifications

How to sign for and handle notifications.

Calling methods

Additional options for calling methods.

Uploading and Downloading Files

How to transfer large data batches correctly.


Secret chats, end-to-end encryption

New feature for end-to-end-encrypted messaging.

Security guidelines

Important checks required in your client application.

Perfect Forward Secrecy

Binding temporary authorization key to permanent ones.


Client optimization

Ways to boost API interactions.

API methods

Available method list

Complete 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

Complete list of available schema versions.

Updates log

Oct 29, 2014 Reorganized Secret Chats documentation: moved Handling Sequence Numbers to a separate document, added section on updating secret chat layers.
Oct 9, 2014 Added Layer 18.
Sep 26, 2014 Added Layer 17.
Aug 29, 2014 New article on Perfect Forward Secrecy. Added Layer 15 and Layer 16.
Apr 4, 2014 Added Layer 13 and Layer 14.
Mar 15, 2014 Added Layer 12.
Dec 21, 2013 Added Layer 11.
Nov 30, 2013 Added Layer 10.
Oct 30, 2013 Added Layer 9.
Oct 8, 2013 New article on secret chats. Added Layer 8.
Sep 6, 2013 New article on TL-schema layers, geochats, new requests. Added layers 2-4.
Aug 27, 2013 New article on client optimizations.
Aug 3, 2013 Updates for documents on polymorphism and vectors in TL. Now undersal vectors ae used in all cases, obsolete language on teemplates has been removed.
Aug 2, 2013 Added update constructor updateMessageID.
Aug 1, 2013 Description for joint updates, added constructor updatesCombined
Jul 31, 2013 Description for file upload/download logic
Jul 29, 2013 Description for gzip-compression use logic for clients
Jul 28, 2013 New article on testing mechanism for forwarding among data centers