Deprecated old docs. This was definitely not the droid you were looking for.
--This article is about Perfect Forward Secrecy in cloud chats, see also PFS in Secret Chats.
-
Telegram supports Perfect Forward Secrecy (PFS).
-To make this possible, the client generates a permanent authorization key using p_q_inner_data and a temporary key using p_q_inner_data_temp. (See Creating an Authorization Key for more info.) These 2 operations may be done in parallel and even using the same connection. The client must save an expires_at unix timestamp expires_at = time + expires_in.
Important: in order to achieve PFS, the client must never use the permanent auth_key_id directly. Every message that is sent to MTProto, must be encrypted by a temp_auth_key_id, that was bound to the perm_auth_key_id.
-An unbound temp_auth_key_id may only be used with the following methods:
- -In order to bind a temporary authorization key to the permanent key the client creates a special binding message and executes the auth.bindTempAuthKey method using temp_auth_key. Once auth.bindTempAuthKey has been executed successfully, the client may signUp / signIn using other auth.* methods and continue using the API as usual; the client must also rewrite client info using initConnection after each binding. Each permanent key may only be bound to one temporary key at a time, binding a new temporary key overwrites the previous one.
-Once the temporary key expires, the client needs to generate a new temporary key using p_q_inner_data_temp. Then it needs to re-bind that new temporary key to the initial permanent key. A new key can also be generated in advance, so that the client has a new key ready by the time the old one has expired.
-For additional security, the client can store the temporary authorization key in RAM only and never save it in persistent storage.
-A temporary authorization key may expire at any moment before expires_at, since such keys are also stored only in the RAM on the server-side. Be prepared to handle resulting MTProto errors correctly (non-existent auth_key_id results in a 404 error).
Temporary payment password
-account.tmpPassword#db64fd34 tmp_password:bytes valid_until:int = account.TmpPassword;| Name | -Type | -Description | -
|---|---|---|
| tmp_password | -bytes | -Temporary password | -
| valid_until | -int | -Validity period | -
The code will be sent via a flash phone call, that will be closed immediately. The phone code will then be the phone number itself, just make sure that the phone number matches the specified pattern.
-auth.sentCodeTypeFlashCall#ab03c6d9 pattern:string = auth.SentCodeType;| Name | -Type | -Description | -
|---|---|---|
| pattern | -string | -pattern to match | -
Some methods require the client to verify if the data obtained from an external source matches a certain pattern.
The admin rights of a user were changed
-channelAdminLogEventActionParticipantToggleAdmin#d5676710 prev_participant:ChannelParticipant new_participant:ChannelParticipant = ChannelAdminLogEventAction;| Name | -Type | -Description | -
|---|---|---|
| prev_participant | -ChannelParticipant | -Previous admin rights | -
| new_participant | -ChannelParticipant | -New admin rights | -
How to handle admin permissions, granular bans and global permissions in channels, groups and supergroups.
No filter
-channelMessagesFilterEmpty#94d42ee7 = ChannelMessagesFilter;This constructor does not require any parameters.
-Fetch only admin participants
-channelParticipantsAdmins#b4608969 = ChannelParticipantsFilter;This constructor does not require any parameters.
-Admin log events
-channels.adminLogResults#ed8af74d events:Vector<ChannelAdminLogEvent> chats:Vector<Chat> users:Vector<User> = channels.AdminLogResults;| Name | -Type | -Description | -
|---|---|---|
| events | -Vector<ChannelAdminLogEvent> | -Admin log events | -
| chats | -Vector<Chat> | -Chats mentioned in events | -
| users | -Vector<User> | -Users mentioned in events | -
Top peers disabled
-contacts.topPeersDisabled#b52c939d = contacts.TopPeers;This constructor does not require any parameters.
-The entire message history has been deleted.
-===8===
-decryptedMessageActionFlushHistory#6719e45c = DecryptedMessageAction;This constructor does not require any parameters.
-Webpage preview
-===45===
-decryptedMessageMediaWebPage#e50511d8 url:string = DecryptedMessageMedia;| Name | -Type | -Description | -
|---|---|---|
| url | -string | -URL of webpage | -
dialogPeerFolder#514519e2 folder_id:int = DialogPeer;| Name | -Type | -Description | -
|---|---|---|
| folder_id | -int | -Peer folder ID, for more info click here | -
Telegram allows placing chats into folders, based on their type, mute status, or other custom criteria, thanks to folder blacklists and whitelists.
Empty draft
-draftMessageEmpty#1b0c841a flags:# date:flags.0?int = DraftMessage;| Name | -Type | -Description | -
|---|---|---|
| flags | -# | -Flags, see TL conditional fields | -
| date | -flags.0?int | -When was the draft last updated | -
An HTTP URL which can be used to automatically log in into translation platform and suggest new emoji replacements. The URL will be valid for 30 seconds after generation
-emojiURL#a575739d url:string = EmojiURL;| Name | -Type | -Description | -
|---|---|---|
| url | -string | -An HTTP URL which can be used to automatically log in into translation platform and suggest new emoji replacements. The URL will be valid for 30 seconds after generation | -
Encrypted file.
-encryptedFile#4a70994c id:long access_hash:long size:int dc_id:int key_fingerprint:int = EncryptedFile;| Name | -Type | -Description | -
|---|---|---|
| id | -long | -File ID | -
| access_hash | -long | -Checking sum depending on user ID | -
| size | -int | -File size in bytes | -
| dc_id | -int | -Number of data centre | -
| key_fingerprint | -int | -32-bit fingerprint of key used for file encryption | -
Return only messages containing URLs
-inputMessagesFilterUrl#7ef0dd87 = MessagesFilter;This constructor does not require any parameters.
-Callback button
-keyboardButtonCallback#35bbdb6b flags:# requires_password:flags.0?true text:string data:bytes = KeyboardButton;| Name | -Type | -Description | -
|---|---|---|
| flags | -# | -Flags, see TL conditional fields | -
| requires_password | -flags.0?true | -Whether the user should verify his identity by entering his 2FA SRP parameters to the messages.getBotCallbackAnswer method. NOTE: telegram and the bot WILL NOT have access to the plaintext password, thanks to SRP. This button is mainly used by the official @botfather bot, for verifying the user's identity before transferring ownership of a bot to another user. | -
| text | -string | -Button text | -
| data | -bytes | -Callback data | -
How to login to a user's account if they have enabled 2FA, how to change password.
-Press an inline callback button and get a callback answer from the bot
Identifies a localization pack
-langPackLanguage#eeca5ce3 flags:# official:flags.0?true rtl:flags.2?true beta:flags.3?true name:string native_name:string lang_code:string base_lang_code:flags.1?string plural_code:string strings_count:int translated_count:int translations_url:string = LangPackLanguage;| Name | -Type | -Description | -
|---|---|---|
| flags | -# | -Flags, see TL conditional fields | -
| official | -flags.0?true | -Whether the language pack is official | -
| rtl | -flags.2?true | -Is this a localization pack for an RTL language | -
| beta | -flags.3?true | -Is this a beta localization pack? | -
| name | -string | -Language name | -
| native_name | -string | -Language name in the language itself | -
| lang_code | -string | -Language code (pack identifier) | -
| base_lang_code | -flags.1?string | -Identifier of a base language pack; may be empty. If a string is missed in the language pack, then it should be fetched from base language pack. Unsupported in custom language packs | -
| plural_code | -string | -A language code to be used to apply plural forms. See https://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html for more info | -
| strings_count | -int | -Total number of non-deleted strings from the language pack | -
| translated_count | -int | -Total number of translated strings from the language pack | -
| translations_url | -string | -Link to language translation interface; empty for custom local language packs | -
Group profile photo removed.
-messageActionChatDeletePhoto#95e3fbef = MessageAction;This constructor does not require any parameters.
-A message was pinned
-messageActionPinMessage#94bd38ed = MessageAction;This constructor does not require any parameters.
-Indicates a range of chat messages
-messageRange#ae30253 min_id:int max_id:int = MessageRange;| Name | -Type | -Description | -
|---|---|---|
| min_id | -int | -Start of range (message ID) | -
| max_id | -int | -End of range (message ID) | -
Configuring parameters did not change.
-messages.dhConfigNotModified#c0e24635 random:bytes = messages.DhConfig;| Name | -Type | -Description | -
|---|---|---|
| random | -bytes | -Random sequence of bytes of assigned length | -
Ordered list of IV blocks
-pageListOrderedItemBlocks#98dd8936 num:string blocks:Vector<PageBlock> = PageListOrderedItem;| Name | -Type | -Description | -
|---|---|---|
| num | -string | -Number of element within ordered list | -
| blocks | -Vector<PageBlock> | -Item contents | -
The phone call was disconnected
-phoneCallDiscardReasonDisconnect#e095c1a0 = PhoneCallDiscardReason;This constructor does not require any parameters.
-Allow all contacts
-privacyValueAllowContacts#fffe1bac = PrivacyRule;This constructor does not require any parameters.
-Bot keyboard
-replyKeyboardMarkup#3502758c flags:# resize:flags.0?true single_use:flags.1?true selective:flags.2?true rows:Vector<KeyboardButtonRow> = ReplyMarkup;| Name | -Type | -Description | -
|---|---|---|
| flags | -# | -Flags, see TL conditional fields | -
| resize | -flags.0?true | -Requests clients to resize the keyboard vertically for optimal fit (e.g., make the keyboard smaller if there are just two rows of buttons). If not set, the custom keyboard is always of the same height as the app's standard keyboard. | -
| single_use | -flags.1?true | -Requests clients to hide the keyboard as soon as it's been used. The keyboard will still be available, but clients will automatically display the usual letter-keyboard in the chat – the user can press a special button in the input field to see the custom keyboard again. | -
| selective | -flags.2?true | -Use this parameter if you want to show the keyboard to specific users only. Targets: 1) users that are @mentioned in the text of the Message object; 2) if the bot's message is a reply (has reply_to_message_id), sender of the original message. Example: A user requests to change the bot‘s language, bot replies to the request with a keyboard to select the new language. Other users in the group don’t see the keyboard. |
-
| rows | -Vector<KeyboardButtonRow> | -Button row | -
MPEG-4 video. MIME type: video/mp4.
storage.fileMp4#b3cea0e4 = storage.FileType;This constructor does not require any parameters.
-A new folder was added
-updateDialogFilter#26ffde7d flags:# id:int filter:flags.0?DialogFilter = Update;| Name | -Type | -Description | -
|---|---|---|
| flags | -# | -Flags, see TL conditional fields | -
| id | -int | -Folder ID | -
| filter | -flags.0?DialogFilter | -Folder info | -
Telegram allows placing chats into folders, based on their type, mute status, or other custom criteria, thanks to folder blacklists and whitelists.
Some featured stickers were marked as read
-updateReadFeaturedStickers#571d2742 = Update;This constructor does not require any parameters.
-Shortened constructor containing info on one new incoming text message from a chat
-updateShortChatMessage#402d5dbb flags:# out:flags.1?true mentioned:flags.4?true media_unread:flags.5?true silent:flags.13?true id:int from_id:int chat_id:int message:string pts:int pts_count:int date:int fwd_from:flags.2?MessageFwdHeader via_bot_id:flags.11?int reply_to:flags.3?MessageReplyHeader entities:flags.7?Vector<MessageEntity> = Updates;| Name | -Type | -Description | -
|---|---|---|
| flags | -# | -Flags, see TL conditional fields | -
| out | -flags.1?true | -Whether the message is outgoing | -
| mentioned | -flags.4?true | -Whether we were mentioned in this message | -
| media_unread | -flags.5?true | -Whether the message contains some unread mentions | -
| silent | -flags.13?true | -If true, the message is a silent message, no notifications should be triggered | -
| id | -int | -ID of the message | -
| from_id | -int | -ID of the sender of the message | -
| chat_id | -int | -ID of the chat where the message was sent | -
| message | -string | -Message | -
| pts | -int | -PTS | -
| pts_count | -int | -PTS count | -
| date | -int | -date | -
| fwd_from | -flags.2?MessageFwdHeader | -Info about a forwarded message | -
| via_bot_id | -flags.11?int | -Info about the inline bot used to generate this message | -
| reply_to | -flags.3?MessageReplyHeader | -Reply (thread) information | -
| entities | -flags.7?Vector<MessageEntity> | -Entities for styled text | -
How to subscribe to updates and handle them properly.
-How to create styled text with message entities
Details about the authorization request, for more info click here »
-urlAuthResultRequest#92d33a0e flags:# request_write_access:flags.0?true bot:User domain:string = UrlAuthResult;| Name | -Type | -Description | -
|---|---|---|
| flags | -# | -Flags, see TL conditional fields | -
| request_write_access | -flags.0?true | -Whether the bot would like to send messages to the user | -
| bot | -User | -Username of a bot, which will be used for user authorization. If not specified, the current bot's username will be assumed. The url's domain must be the same as the domain linked with the bot. See Linking your domain to the bot for more details. | -
| domain | -string | -The domain name of the website on which the user will log in. | -
Handle Seamless Telegram Login URL authorization requests.
Online status of the user.
-userStatusOnline#edb93949 expires:int = UserStatus;| Name | -Type | -Description | -
|---|---|---|
| expires | -int | -Time to expiration of the current online status | -
The preview of the webpage hasn't changed
-webPageNotModified#7311ca11 flags:# cached_page_views:flags.0?int = WebPage;| Name | -Type | -Description | -
|---|---|---|
| flags | -# | -Flags, see TL conditional fields | -
| cached_page_views | -flags.0?int | -Page view count | -
Cancel the code that was sent to verify an email to use as 2FA recovery method.
-boolFalse#bc799737 = Bool;
-boolTrue#997275b5 = Bool;
----functions---
-account.cancelPasswordEmail#c1cbd5b6 = Bool;This constructor does not require any parameters.
-How to login to a user's account if they have enabled 2FA, how to change password.
Create a theme
-theme#28f1114 flags:# creator:flags.0?true default:flags.1?true id:long access_hash:long slug:string title:string document:flags.2?Document settings:flags.3?ThemeSettings installs_count:int = Theme;
----functions---
-account.createTheme#8432c21f flags:# slug:string title:string document:flags.2?InputDocument settings:flags.3?InputThemeSettings = Theme;| Name | -Type | -Description | -
|---|---|---|
| flags | -# | -Flags, see TL conditional fields | -
| slug | -string | -Unique theme ID | -
| title | -string | -Theme name | -
| document | -flags.2?InputDocument | -Theme file | -
| settings | -flags.3?InputThemeSettings | -Theme settings | -
Returns list of chats with non-default notification settings
-updatesTooLong#e317af7e = Updates;
-updateShortMessage#2296d2c8 flags:# out:flags.1?true mentioned:flags.4?true media_unread:flags.5?true silent:flags.13?true id:int user_id:int message:string pts:int pts_count:int date:int fwd_from:flags.2?MessageFwdHeader via_bot_id:flags.11?int reply_to:flags.3?MessageReplyHeader entities:flags.7?Vector<MessageEntity> = Updates;
-updateShortChatMessage#402d5dbb flags:# out:flags.1?true mentioned:flags.4?true media_unread:flags.5?true silent:flags.13?true id:int from_id:int chat_id:int message:string pts:int pts_count:int date:int fwd_from:flags.2?MessageFwdHeader via_bot_id:flags.11?int reply_to:flags.3?MessageReplyHeader entities:flags.7?Vector<MessageEntity> = Updates;
-updateShort#78d4dec1 update:Update date:int = Updates;
-updatesCombined#725b04c3 updates:Vector<Update> users:Vector<User> chats:Vector<Chat> date:int seq_start:int seq:int = Updates;
-updates#74ae4240 updates:Vector<Update> users:Vector<User> chats:Vector<Chat> date:int seq:int = Updates;
-updateShortSentMessage#11f1331c flags:# out:flags.1?true id:int pts:int pts_count:int date:int media:flags.9?MessageMedia entities:flags.7?Vector<MessageEntity> = Updates;
----functions---
-account.getNotifyExceptions#53577479 flags:# compare_sound:flags.1?true peer:flags.0?InputNotifyPeer = Updates;| Name | -Type | -Description | -
|---|---|---|
| flags | -# | -Flags, see TL conditional fields | -
| compare_sound | -flags.1?true | -If true, chats with non-default sound will also be returned | -
| peer | -flags.0?InputNotifyPeer | -If specified, only chats of the specified category will be returned | -
Verify a new phone number to associate to the current account
-auth.sentCode#5e002502 flags:# type:auth.SentCodeType phone_code_hash:string next_type:flags.1?auth.CodeType timeout:flags.2?int = auth.SentCode;
----functions---
-account.sendChangePhoneCode#82574ae5 phone_number:string settings:CodeSettings = auth.SentCode;| Name | -Type | -Description | -
|---|---|---|
| phone_number | -string | -New phone number | -
| settings | -CodeSettings | -Phone code settings | -
| Code | -Type | -Description | -
|---|---|---|
| 400 | -PHONE_NUMBER_INVALID | -The phone number is invalid | -
Login using a redirected login token, generated in case of DC mismatch during QR code login.
-For more info, see login via QR code.
-auth.loginToken#629f1980 expires:int token:bytes = auth.LoginToken;
-auth.loginTokenMigrateTo#68e9916 dc_id:int token:bytes = auth.LoginToken;
-auth.loginTokenSuccess#390d5c5e authorization:auth.Authorization = auth.LoginToken;
----functions---
-auth.importLoginToken#95ac5ce4 token:bytes = auth.LoginToken;| Name | -Type | -Description | -
|---|---|---|
| token | -bytes | -Login token | -
| Code | -Type | -Description | -
|---|---|---|
| 400 | -AUTH_TOKEN_EXPIRED | -The authorization token has expired | -
QR code login flow
Delete the history of a supergroup
-boolFalse#bc799737 = Bool;
-boolTrue#997275b5 = Bool;
----functions---
-channels.deleteHistory#af369d42 channel:InputChannel max_id:int = Bool;| Name | -Type | -Description | -
|---|---|---|
| channel | -InputChannel | -Supergroup whose history must be deleted | -
| max_id | -int | -ID of message up to which the history must be deleted | -
| Code | -Type | -Description | -
|---|---|---|
| 400 | -CHANNEL_INVALID | -The provided channel is invalid | -
| 400 | -CHANNEL_PRIVATE | -You haven't joined this channel/supergroup | -
How to handle channels, supergroups, groups, and what's the difference between them.
Returns localized text of a text message with an invitation.
-help.inviteText#18cb9f78 message:string = help.InviteText;
----functions---
-help.getInviteText#4d392343 = help.InviteText;This constructor does not require any parameters.
-Get MTProxy/Public Service Announcement information
-help.promoDataEmpty#98f6ac75 expires:int = help.PromoData;
-help.promoData#8c39793f flags:# proxy:flags.0?true expires:int peer:Peer chats:Vector<Chat> users:Vector<User> psa_type:flags.1?string psa_message:flags.2?string = help.PromoData;
----functions---
-help.getPromoData#c0977421 = help.PromoData;This constructor does not require any parameters.
-Save get all message drafts.
-updatesTooLong#e317af7e = Updates;
-updateShortMessage#2296d2c8 flags:# out:flags.1?true mentioned:flags.4?true media_unread:flags.5?true silent:flags.13?true id:int user_id:int message:string pts:int pts_count:int date:int fwd_from:flags.2?MessageFwdHeader via_bot_id:flags.11?int reply_to:flags.3?MessageReplyHeader entities:flags.7?Vector<MessageEntity> = Updates;
-updateShortChatMessage#402d5dbb flags:# out:flags.1?true mentioned:flags.4?true media_unread:flags.5?true silent:flags.13?true id:int from_id:int chat_id:int message:string pts:int pts_count:int date:int fwd_from:flags.2?MessageFwdHeader via_bot_id:flags.11?int reply_to:flags.3?MessageReplyHeader entities:flags.7?Vector<MessageEntity> = Updates;
-updateShort#78d4dec1 update:Update date:int = Updates;
-updatesCombined#725b04c3 updates:Vector<Update> users:Vector<User> chats:Vector<Chat> date:int seq_start:int seq:int = Updates;
-updates#74ae4240 updates:Vector<Update> users:Vector<User> chats:Vector<Chat> date:int seq:int = Updates;
-updateShortSentMessage#11f1331c flags:# out:flags.1?true id:int pts:int pts_count:int date:int media:flags.9?MessageMedia entities:flags.7?Vector<MessageEntity> = Updates;
----functions---
-messages.getAllDrafts#6a3f8d65 = Updates;This constructor does not require any parameters.
-Updates, contains all the latest updateDraftMessage updates related to all chats with drafts.
-How to handle message drafts
Manually mark dialog as unread
-boolFalse#bc799737 = Bool;
-boolTrue#997275b5 = Bool;
----functions---
-messages.markDialogUnread#c286d98f flags:# unread:flags.0?true peer:InputDialogPeer = Bool;| Name | -Type | -Description | -
|---|---|---|
| flags | -# | -Flags, see TL conditional fields | -
| unread | -flags.0?true | -Mark as unread/read | -
| peer | -InputDialogPeer | -Dialog | -
Optional: notify the server that the user is currently busy in a call: this will automatically refuse all incoming phone calls until the current phone call is ended.
-boolFalse#bc799737 = Bool;
-boolTrue#997275b5 = Bool;
----functions---
-phone.receivedCall#17d54f61 peer:InputPhoneCall = Bool;| Name | -Type | -Description | -
|---|---|---|
| peer | -InputPhoneCall | -The phone call we're currently in | -
| Code | -Type | -Description | -
|---|---|---|
| 400 | -CALL_ALREADY_DECLINED | -The call was already declined | -
| 400 | -CALL_PEER_INVALID | -The provided call peer object is invalid | -