Channels are a tool for broadcasting your messages to large audiences. They can have an unlimited number of subscribers, they can be public with a permanent URL and each post in a channel has its own view counter. +Technically, they are represented by channel constructors.
+Supergroups are a powerful tool for building communities and can support up to 200,000 members each.
+Technically, supergroups are actually channels: they are represented by channel constructors, with the megagroup flag set to true.
Channels and supergroup can be created using the channels.createChannel method, by setting the appropriate broadcast or megagroup flags.
+Supergroups can also be assigned a geo_point to become geochats.
In previous versions of telegram, only normal groups (represented by chat constructors) could be created using messages.createChat: these groups have fewer features, and can only have 200 members at max.
+To upgrade a legacy group to a supergroup, messages.migrateChat can be used.
+The chats field of the result will have two objects:
migrated_to field, indicating the address of the new supergroupWhen getting full info about the migrated channel, the channelFull object will have migrated_from_chat_id and migrated_from_max_id fields indicating the original ID of the chat, and the message ID in the original chat at which the group was migrated.
All users of the chat will receive an updateNewMessage from the old chat with a messageService containing a messageActionChatMigrateTo constructor.
+All new messages have to be sent to the new supergroup.
+When working with migrated groups clients need to handle loading of the message history (as well as search results et cetera) from both the legacy group and the new supergroup. This is done by merging the two messages lists (requested with different Peer values) client side.
+Channels, legacy groups and supergroups allow setting granular permissions both for admins and specific users; channels, supergroups and legacy groups also allow setting global granular permissions for users.
+For more info on how to set and modify rights, see here ».
+Telegram allows pinning multiple messages on top in a chat, group, supergroup or channel.
+See here » for more info on pinning and unpinning messages.
+Groups can be associated to a channel as a discussion group, to allow users to discuss about posts.
+For more info on how to set a discussion group in channel, see here »
+Both supergroups and channels offer a so-called admin log, a log of recent relevant supergroup and channel actions, like the modification of group/channel settings or information on behalf of an admin, user kicks and bans, and more.
+See here » for more info.
Assigns a new big encrypted file (over 10Mb in size), saved in parts using the method upload.saveBigFilePart.
+inputEncryptedFileBigUploaded#2dc173c8 id:long parts:int key_fingerprint:int = InputEncryptedFile;| Name | +Type | +Description | +
|---|---|---|
| id | +long | +Random file id, created by the client | +
| parts | +int | +Number of saved parts | +
| key_fingerprint | +int | +32-bit imprint of the key used to encrypt the file | +
Saves a part of a large file (over 10Mb in size) to be later passed to one of the methods.
Unknown KDF (most likely, the client is outdated and does not support the specified KDF algorithm)
+passwordKdfAlgoUnknown#d45ab096 = PasswordKdfAlgo;This constructor does not require any parameters.
+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.