TDLib is a fully functional Telegram client which takes care of all networking, local storage and data consistency details. In this tutorial we describe the main concepts understanding of which is required for effecient TDLib usage.
In this text, Client means an interface for interaction with a TDLib instance and Application means the program that uses TDLib to interact with Telegram.
The main TDLib API is fully-asyncronous. An Application can send a request to TDLib through Client.send method and receive a response asynchronously through the Client.receive method when it becomes available. The exact naming of these methods and the way in which requests are matched with responses is different for different TDLib interfaces, but the concept as a whole remains the same. For example, in TDLib JSON interface these methods are called td_json_client_send and td_json_client_receive, and their @extra field should be used to match requests with the corresponding responses.
In a high-level interface used by an Application the matching of responses with corresponding requests is often automated and transformed by some wrapper into a call to a continuation, a callback, a Promise or a Future to simplify the handling of responses.
Aside from responses to requests, an Application receives a lot of important data through incoming updates. Updates are used to pass new data from TDLib to the Application and often control the behavior of the Application, leaving no chance to implement something wrong. The correct handling of updates is crucial for creating an Application that is efficient and works correctly.
You can find a list of all available TDLib API methods in our web-documentation. You can also find the descriptions of all available TDLib methods and classes in the TDLIB API scheme.
TDLib can be used from any programming language. You can find a lot of examples of TDLib-based frameworks in various programming languages in our examples section.
This section describes the basic notions required for understanding the TDLib API. If you have used the TDLib-based Telegram Bot API most of them should be already familiar to you.
Telegram is a messenger, so the main object is a message. Each message belongs to some chat and has a unique identifier within that chat. Messages inside a chat should be sorted by that identifier. Telegram supports many different kinds of messages, so a message can have many different kinds of message content. Currently there are more than 40 different kinds of message content, for example messageText for text messages, messagePhoto for photos, or messageScreenshotTaken for notifications about screenshots taken by the other party.
A Telegram user is called user. Each user has a unique identifier and a first name, and can also have an optional last name, username and profile photo among other useful fields. Bot is a special type of user which can be controlled through the Telegram Bot API.
Each chat has members, i.e. users that immediately receive all messages sent to the chat. Currently there are 6 possible chat member statuses which describe different rights and restrictions a user can have in a chat, ranging from the owner of the chat who has more rights in the chat than any other user, to a user banned in the chat who is banned in the chat and can't return to it by self or even view chat messages, even if the chat is public.
As noted earlier, each message belongs to a chat. Currently there are 4 different types of chats on Telegram:
Each chat has a unique identifier, a title and an optional chat photo. Chats comprise sorted lists shown to the user, position in which is determined, roughly speaking, by the time of latest activity. The correct order of chats in chat lists is maintained by TDLib, so the Application only needs to listen to updates that change the chat.positions field and sort all chats by the pair (position.order, chat.id) in a given position.list.
Messages, chat photos and many other objects can have a file inside of them. Each file has an identifier and may be available locally on a hard drive or remotely on a cloud server. A file can be usually downloaded to the local hard drive or uploaded to Telegram cloud servers.
Messages with media content like photos or videos can have a short accompanying text called caption. The texts of text messages and media captions can contain fragments, which should be formatted in some unusual way. These fragments are called text entities and the combination of a text and its entities are referred together as a formatted text.
TDLib sends a lot of important data to the Application through updates. For example, if there is a user unknown to the Application, or some data about a user has changed, then TDLib immediately sends an updateUser to the Application.
You can find list of all currently available updates here »
Authorization is an example of a behavior, which is controlled by TDLib through updates. Whenever an action is required to proceed with user authorization, the Application receives an updateAuthorizationState with the description of the current AuthorizationState. The Application only needs to handle this update appropriately to correctly implement user authorization.
The first authorization state received by the Application is always of the type authorizationStateWaitTdlibParameters. When it is received, the Application should provide parameters for TDLib initialization by calling the setTdlibParameters method. In this method the Application will need to specify, among other parameters:
After call to setTdlibParameters in case of success Application will receive updateAuthorizationState with new state and just needs to handle that update, nothing should be done explicitly. If setTdlibParameters fails, then authorization state is not changed and the Application should try to handle the current authorization state again.
The second received authorization state is always authorizationStateWaitEncryptionKey. When it is received, the database encryption key should be provided through a call to checkDatabaseEncryptionKey. For most mobile apps, you can provide an empty database encryption key here (more info). If user isn't authorized yet, then some of authorizationStateWaitPhoneNumber, authorizationStateWaitCode, authorizationStateWaitRegistration and authorizationStateWaitPassword authorization states may be received. After completing these authorization steps, the Application will receive authorizationStateReady, meaning that authorization was successful and ordinary requests can be sent now.
You can find complete examples of user authorization in our Java and C# examples.
To send any kind of message, the Application needs to call the method sendMessage providing a chat identifier and the content of the message to be sent. For example, the Application can send a text message using inputMessageText class as input message content, a photo using inputMessagePhoto or a location using inputMessageLocation. The Application can use inputFileLocal as InputFile in these objects to send a local file from the hard drive.
You can find examples of sending a text message in our Java and C# examples.
All updates and responses to requests should be handled in the order they are received. Here is a list of the most important updates and how they should be handled:
chat_id, it never needs to use a getChat request to receive the chat object. Instead it should maintain a cache of chats received through this update and take all the necessary data about chats from this cache.user_id, it never needs to use the getUser request to receive the user object. Instead it should maintain a cache of users received through this update and take all the necessary data about users from this cache.basic_group_id, it never needs to use the getBasicGroup request to receive the basicGroup object. Instead it should maintain a cache of basic groups received through this update and take all the necessary data about basic groups from this cache.supergroup_id, it never needs to use the getSupergroup request to receive the supergroup object. Instead it should maintain a cache of supergroups received through this update and take all the necessary data about supergroups from this cache.secret_chat_id, it never needs to use the getSecretChat request to receive the secret chat object. Instead it should maintain a cache of secret chats received through this update and take all the necessary data about secret chats from this cache.For a full list of currently available updates see the documentation for the Update class.
You can find an example of correct handling of some updates in our Java example.
Currently there are 3 different types of chat lists:
- Main chat list.
- Archive chat list.
- A folder chat list.
The positions of chats in chat lists are managed by TDLib, so the Application only needs to listen to updates that change the chat.positions field, maintain the list of all chats, sorted by the pair (position.order, chat.id) in descending order, and call getChats only if there are not enough known chats. Responses to getChats can be often safely ignored, because if all updates changing chat.positions are processed correctly, then the chat list should already be up to date. Because chats are sorted in descending order of position.order, the first request to getChats should have offset_order == 2^63 - 1 == 9223372036854775807 — the maximum possible value that a signed 64-bit integer can have. For optimal performance, the number of returned chats is chosen by TDLib and can be smaller than the specified limit. If the Application needs more chats, it should repeat the request with adjusted offset_order and offset_chat_id parameters.
You can find an example of retrieving the Main chat list in our Java example.
The Application can use the getChatHistory method to get messages in a chat. The messages will be returned in the reverse chronological order (i.e., in descending order of message_id). The Application can pass from_message_id == 0 to get messages from the last message. To get more messages than can be returned in one response, the Application needs to pass the identifier of the last message it has received as from_message_id to next request. For optimal performance, the number of the returned messages is chosen by TDLib and can be smaller than the specified limit. If the Application needs more messages, it needs to adjust the from_message_id parameter and repeat the request.