Available TL-layers

Below you will find information on schema changes. For more details on the use of layers, see Invoking API methods.

Layer 18

Added username support and a new type of updates for service messages.

Schema changes

• Added methods account.checkUsername and account.updateUsername for setting up a username, as well as the method contacts.search that allows searching for publicly available users by username.
• username field added to constructors of the type User and to the updateUserName constructor.
• Added new update constructor updateServiceNotification for receiving service messages.

Schema

contactFound user_id:int = ContactFound;

contacts.found results:Vector<ContactFound> users:Vector<User> = contacts.Found;

updateUserName user_id:int first_name:string last_name:string username:string = Update;

userSelf id:int first_name:string last_name:string username:string phone:string photo:UserProfilePhoto status:UserStatus inactive:Bool = User;
userContact id:int first_name:string last_name:string username:string access_hash:long phone:string photo:UserProfilePhoto status:UserStatus = User;
userRequest id:int first_name:string last_name:string username:string access_hash:long phone:string photo:UserProfilePhoto status:UserStatus = User;
userForeign id:int first_name:string last_name:string username:string access_hash:long photo:UserProfilePhoto status:UserStatus = User;
userDeleted id:int first_name:string last_name:string username:string = User;

updateServiceNotification type:string message:string media:MessageMedia popup:Bool = Update;

---functions---

account.checkUsername username:string = Bool;
account.updateUsername username:string = User;

contacts.search q:string limit:int = contacts.Found;

invokeWithLayer18#1c900537 {X:Type} query:!X = X;

Layer 17

Added new events for recording and uploading media, selecting contacts and locations to share.

Read status for multimedia (messages containing messageMediaVideo or messageMediaAudio) was moved to the new method messages.readMessageContents. In case read_contents is not passed or messages.readHistory is used with an older layer, messages will be marked as read in the traditional way.

Schema changes

• Added new type SendMessageAction for user actions aside from typing (recording, uploading media, etc.). It is used in updates updateUserTyping, updateChatUserTyping, in the method messages.setTyping, and in the new encrypted service message decryptedMessageActionTyping.
• unread and out parameters in the constructors of the Message type were joined to form the new flags parameter, containing a flag mask.
• Added new method messages.readMessageContents, to be called once the user listened to a voice message or watched a video.
• Added parameters for end-to-end encrypted messages in_seq_no, out_seq_no and ttl.
• Added mime_type field to secret chat audio and video constructors.

Schema

sendMessageTypingAction = SendMessageAction;
sendMessageCancelAction = SendMessageAction;
sendMessageRecordVideoAction = SendMessageAction;
sendMessageUploadVideoAction = SendMessageAction;
sendMessageRecordAudioAction = SendMessageAction;
sendMessageUploadAudioAction = SendMessageAction;
sendMessageUploadPhotoAction = SendMessageAction;
sendMessageUploadDocumentAction = SendMessageAction;
sendMessageGeoLocationAction = SendMessageAction;
sendMessageChooseContactAction = SendMessageAction;

updateUserTyping user_id:int action:SendMessageAction = Update;
updateChatUserTyping chat_id:int user_id:int action:SendMessageAction = Update;

// Message object
message flags:int id:int from_id:int to_id:Peer date:int message:string media:MessageMedia = Message;
messageForwarded flags:int id:int fwd_from_id:int fwd_date:int from_id:int to_id:Peer date:int message:string media:MessageMedia = Message;
messageService flags:int id:int from_id:int to_id:Peer date:int action:MessageAction = Message;

---functions---

messages.setTyping peer:InputPeer action:SendMessageAction = Bool;

messages.readHistory peer:InputPeer max_id:int offset:int read_contents:Bool = messages.AffectedHistory;
messages.readMessageContents id:Vector<int> = Vector<int>;

invokeWithLayer17#50858a19 {X:Type} query:!X = X;

End-to-end schema

===17===


// Layer
decryptedMessageLayer random_bytes:bytes layer:int in_seq_no:int out_seq_no:int message:DecryptedMessage = DecryptedMessageLayer;

decryptedMessageMediaAudio duration:int mime_type:string size:int key:bytes iv:bytes = DecryptedMessageMedia;
decryptedMessageMediaVideo thumb:bytes thumb_w:int thumb_h:int duration:int mime_type:string w:int h:int size:int key:bytes iv:bytes = DecryptedMessageMedia;

sendMessageTypingAction = SendMessageAction;
sendMessageCancelAction = SendMessageAction;
sendMessageRecordVideoAction = SendMessageAction;
sendMessageUploadVideoAction = SendMessageAction;
sendMessageRecordAudioAction = SendMessageAction;
sendMessageUploadAudioAction = SendMessageAction;
sendMessageUploadPhotoAction = SendMessageAction;
sendMessageUploadDocumentAction = SendMessageAction;
sendMessageGeoLocationAction = SendMessageAction;
sendMessageChooseContactAction = SendMessageAction;

decryptedMessageActionNotifyLayer layer:int = DecryptedMessageAction;
decryptedMessageActionTyping action:SendMessageAction = DecryptedMessageAction;

decryptedMessage random_id:long ttl:int message:string media:DecryptedMessageMedia = DecryptedMessage;
decryptedMessageService random_id:long action:DecryptedMessageAction = DecryptedMessage;

Layer 16

Added new sms_type = 5 in the method auth.sendCode.

Schema changes

• Added new constructor: auth.sentAppCode to determine whether a code was sent via Telegram.
• Added new method auth.sendSms to force re-sending a code via SMS.

Schema

auth.sentAppCode phone_registered:Bool phone_code_hash:string send_call_timeout:int is_password:Bool = auth.SentCode;

---functions---

auth.sendSms phone_number:string phone_code_hash:string = Bool;

invokeWithLayer16#cf5f0987 {X:Type} query:!X = X;

Layer 15

Modified behavior of the offset parameter in the method messages.getHistory. From now on it's possible to combine message_id offset and a numeric offset.

Schema

invokeWithLayer15#b4418b64 {X:Type} query:!X = X;

Layer 14

Schema changes

• Added new update constructors: updateUserBlocked and updateNotifySettings to sync notification settings and blacklists between devices.
• Added notify_settings field to the dialog constructor.

Schema

notifyPeer peer:Peer = NotifyPeer;
notifyUsers = NotifyPeer;
notifyChats = NotifyPeer;
notifyAll = NotifyPeer;

dialog peer:Peer top_message:int unread_count:int notify_settings:PeerNotifySettings = Dialog;

updateUserBlocked user_id:int blocked:Bool = Update;
updateNotifySettings peer:NotifyPeer notify_settings:PeerNotifySettings = Update;

---functions---

invokeWithLayer14#2b9b08fa {X:Type} query:!X = X;

Layer 13

Schema changes

• Added mime_type field to all audio and video constructors.
• Added new service message types in secret chats: messages read, messages deleted, screenshot taken, chat history cleared and API layer used by client notifications.
• Added retry_contacts field to the contacts.importedContacts constructor: ids of contacts, that will have to be imported at a later date.

Schema

contacts.importedContacts imported:Vector<ImportedContact> retry_contacts:Vector<long> users:Vector<User> = contacts.Im    portedContacts;

inputMediaUploadedAudio file:InputFile duration:int mime_type:string = InputMedia;
inputMediaUploadedVideo file:InputFile duration:int w:int h:int mime_type:string = InputMedia;
inputMediaUploadedThumbVideo file:InputFile thumb:InputFile duration:int w:int h:int mime_type:string = InputMedia;

audio id:long access_hash:long user_id:int date:int duration:int mime_type:string size:int dc_id:int = Audio;
video id:long access_hash:long user_id:int date:int caption:string duration:int mime_type:string size:int thumb:PhotoSize dc_id:int w:int h:int = Video;

---functions---

invokeWithLayer13#427c8ea2 {X:Type} query:!X = X;

Layer 12

Schema changes

• Added method help.getSupport for obtaining support user id.
• Added broadcast_size_max field to the constructor config, contaning maximum number of broadcast recipients.
• Added send_call_timeout field to the constructor auth.sentCode, containing required delay before calling auth.sendCall. New field is_password in the same constructor.

Schema

auth.sentCode phone_registered:Bool phone_code_hash:string send_call_timeout:int is_password:Bool = auth.SentCode;

config date:int test_mode:Bool this_dc:int dc_options:Vector<DcOption> chat_size_max:int broadcast_size_max:int = Config;

help.support phone_number:string user:User = help.Support;

---functions---

help.getSupport = help.Support;

invokeWithLayer12#dda60d3c {X:Type} query:!X = X;

Layer 11

Schema changes

• The nonce parameter was removed from secret chat constructors. For purposes of backward compatibility, in all previous layers this field will contain empty bytes.

Schema

encryptedChatRequested id:int access_hash:long date:int admin_id:int participant_id:int g_a:bytes = EncryptedChat;
encryptedChat id:int access_hash:long date:int admin_id:int participant_id:int g_a_or_b:bytes key_fingerprint:long = EncryptedChat;

---functions---

invokeWithLayer11#a6b88fdf {X:Type} query:!X = X;

Layer 10

Added brief constructors for editing group members.
Added new attachment types for ordinary and secret chats.

Schema changes

• Added new update contructors: updateChatParticipantAdd and updateChatParticipantDelete.
• Added new media types: Document, Audio, along with rescpective attachment constructors.
• If the client doesn't support Layer 10, it will receive messageMediaUnsupported constructors instead of the messageMediaDocument and messageMediaAudio constructors.

Schema

updateChatParticipantAdd chat_id:int user_id:int inviter_id:int version:int = Update;
updateChatParticipantDelete chat_id:int user_id:int version:int = Update;


inputMediaUploadedAudio file:InputFile duration:int = InputMedia;
inputMediaAudio id:InputAudio = InputMedia;

inputMediaUploadedDocument file:InputFile file_name:string mime_type:string = InputMedia;
inputMediaUploadedThumbDocument file:InputFile thumb:InputFile file_name:string mime_type:string = InputMedia;
inputMediaDocument id:InputDocument = InputMedia;

messageMediaDocument document:Document = MessageMedia;
messageMediaAudio audio:Audio = MessageMedia;

// Input Audio
inputAudioEmpty = InputAudio;
inputAudio id:long access_hash:long = InputAudio;

// Input Document
inputDocumentEmpty = InputDocument;
inputDocument id:long access_hash:long = InputDocument;

// Input location
inputAudioFileLocation id:long access_hash:long = InputFileLocation;
inputDocumentFileLocation id:long access_hash:long = InputFileLocation;


decryptedMessageMediaDocument thumb:bytes thumb_w:int thumb_h:int file_name:string mime_type:string size:int key:bytes iv:bytes = DecryptedMessageMedia;
decryptedMessageMediaAudio duration:int size:int key:bytes iv:bytes = DecryptedMessageMedia;


// Audio object
audioEmpty id:long = Audio;
audio id:long access_hash:long user_id:int date:int duration:int size:int dc_id:int = Audio;

// Video object
documentEmpty id:long = Document;
document id:long access_hash:long user_id:int date:int file_name:string mime_type:string size:int thumb:PhotoSize dc_id:int = Document;

---functions---

invokeWithLayer10#39620c41 {X:Type} query:!X = X;
PUSH-notifications

Added MESSAGE_DOC, MESSAGE_AUDIO notifications — a message with document or audio received
Added CHAT_MESSAGE_DOC, CHAT_MESSAGE_AUDIO notifications —  a message with document or audio received in a group

Layer 9

Increased efficiency when loading big files.
Added important checks for certain methods.

Schema changes

• Added new upload.saveBigFilePart method, constructors inputFileBig, inputEncryptedFileBigUploaded to optimize saving parts of big files. See the updated article on Uploading files for details.
• Added a check whether the initConnection method was called with all required parameters before making other API calls. See the updated article on Calling methods for details.
• Added availability check for lang_code parameters when calling methods auth.sendCode, account.registerDevice
• Added availability check for random_id parameters in all message sending methods: messages.sendMessage, messages.sendMedia, messages.forwardMessage

Schema

inputFileBig id:long parts:int name:string = InputFile;

inputEncryptedFileBigUploaded id:long parts:int key_fingerprint:int = InputEncryptedFile;

---functions---

upload.saveBigFilePart file_id:long file_part:int file_total_parts:int bytes:bytes = Bool;

initConnection#69796de9 {X:Type} api_id:int device_model:string system_version:string app_version:string lang_code:string query:!X = X;

invokeWithLayer9#76715a63 {X:Type} query:!X = X;

Layer 8

Added support for end-to-end encryption in secret chats. More…

Schema changes

• Added many constructors and methods for secret chats.
• Added qts field in constructor updates.state.
• Added 4 new constructors of Update type

Schema

updateNewEncryptedMessage message:EncryptedMessage qts:int = Update;
updateEncryptedChatTyping chat_id:int = Update;
updateEncryption chat:EncryptedChat date:int = Update;
updateEncryptedMessagesRead chat_id:int max_date:int = Update;

// EncryptedChat object
encryptedChatEmpty id:int = EncryptedChat;
encryptedChatWaiting id:int access_hash:long date:int admin_id:int participant_id:int = EncryptedChat;
encryptedChatRequested id:int access_hash:long date:int admin_id:int participant_id:int g_a:bytes = EncryptedChat;
encryptedChat id:int access_hash:long date:int admin_id:int participant_id:int g_a_or_b:bytes key_fingerprint:long = EncryptedChat;
encryptedChatDiscarded id:int = EncryptedChat;

inputEncryptedChat chat_id:int access_hash:long = InputEncryptedChat;

// EncryptedFile object
encryptedFileEmpty = EncryptedFile;
encryptedFile id:long access_hash:long size:int dc_id:int key_fingerprint:int = EncryptedFile;

inputEncryptedFileEmpty = InputEncryptedFile;
inputEncryptedFileUploaded id:long parts:int md5_checksum:string key_fingerprint:int = InputEncryptedFile;
inputEncryptedFile id:long access_hash:long = InputEncryptedFile;

inputEncryptedFileLocation id:long access_hash:long = InputFileLocation;

// Encrypted message
encryptedMessage random_id:long chat_id:int date:int bytes:bytes file:EncryptedFile = EncryptedMessage;
encryptedMessageService random_id:long chat_id:int date:int bytes:bytes = EncryptedMessage;

// Diffie-Hellman config
messages.dhConfigNotModified random:bytes = messages.DhConfig;
messages.dhConfig g:int p:bytes version:int random:bytes = messages.DhConfig;

messages.sentEncryptedMessage date:int = messages.SentEncryptedMessage;
messages.sentEncryptedFile date:int file:EncryptedFile = messages.SentEncryptedMessage;

// Updated state with qts
updates.state pts:int qts:int date:int seq:int unread_count:int = updates.State;
updates.difference new_messages:Vector<Message> new_encrypted_messages:Vector<EncryptedMessage> other_updates:Vector<Update> chats:Vector<Chat> users:Vector<User> state:updates.State = updates.Difference;
updates.differenceSlice new_messages:Vector<Message> new_encrypted_messages:Vector<EncryptedMessage> other_updates:Vector<Update> chats:Vector<Chat> users:Vector<User> intermediate_state:updates.State = updates.Difference;

---functions---

messages.getDhConfig version:int random_length:int = messages.DhConfig;
messages.requestEncryption user_id:InputUser random_id:int g_a:bytes = EncryptedChat;
messages.acceptEncryption peer:InputEncryptedChat g_b:bytes key_fingerprint:long = EncryptedChat;
messages.discardEncryption chat_id:int = Bool;

messages.setEncryptedTyping peer:InputEncryptedChat typing:Bool = Bool;
messages.readEncryptedHistory peer:InputEncryptedChat max_date:int = Bool;
messages.sendEncrypted peer:InputEncryptedChat random_id:long data:bytes = messages.SentEncryptedMessage;
messages.sendEncryptedFile peer:InputEncryptedChat random_id:long data:bytes file:InputEncryptedFile = messages.SentEncryptedMessage;
messages.sendEncryptedService peer:InputEncryptedChat random_id:long data:bytes = messages.SentEncryptedMessage;
messages.receivedQueue max_qts:int = Vector<long>;

updates.getDifference pts:int date:int qts:int = updates.Difference;

invokeWithLayer8#e9abd9fd {X:Type} query:!X = X;

PUSH-notifications

• Added notification of ENCRYPTION_REQUEST type — a contact requested secret chat creation
• Added notification of ENCRYPTION_ACCEPT type — a contact confirmed secret chat creation
• Added notification of ENCRYPTED_MESSAGE type — a contact sent message in a secret chat

End-to-end schema

===8===
decryptedMessage random_id:long random_bytes:bytes message:string media:DecryptedMessageMedia = DecryptedMessage;
decryptedMessageService random_id:long random_bytes:bytes action:DecryptedMessageAction = DecryptedMessage;

decryptedMessageMediaEmpty = DecryptedMessageMedia;
decryptedMessageMediaPhoto thumb:bytes thumb_w:int thumb_h:int w:int h:int size:int key:bytes iv:bytes = DecryptedMessageMedia;
decryptedMessageMediaVideo thumb:bytes thumb_w:int thumb_h:int duration:int w:int h:int size:int key:bytes iv:bytes = DecryptedMessageMedia;
decryptedMessageMediaGeoPoint lat:double long:double = DecryptedMessageMedia;
decryptedMessageMediaContact phone_number:string first_name:string last_name:string user_id:int = DecryptedMessageMedia;

decryptedMessageActionSetMessageTTL ttl_seconds:int = DecryptedMessageAction;

decryptedMessageMediaDocument thumb:bytes thumb_w:int thumb_h:int file_name:string mime_type:string size:int key:bytes iv:bytes = DecryptedMessageMedia;
decryptedMessageMediaAudio duration:int size:int key:bytes iv:bytes = DecryptedMessageMedia;

decryptedMessageActionReadMessages random_ids:Vector<long> = DecryptedMessageAction;
decryptedMessageActionDeleteMessages random_ids:Vector<long> = DecryptedMessageAction;
decryptedMessageActionScreenshotMessages random_ids:Vector<long> = DecryptedMessageAction;
decryptedMessageActionFlushHistory = DecryptedMessageAction;

Layer 7

Added wallpaper constructor wallPaperSolid.

Schema

wallPaperSolid id:int title:string bg_color:int color:int = WallPaper;
---functions---
invokeWithLayer7#a5be56d3 {X:Type} query:!X = X;

Layer 6

Added location identifiers from foursquare.

Schema

geoChat id:int access_hash:long title:string address:string venue:string geo:GeoPoint photo:ChatPhoto participants_count:int date:int checked_in:Bool version:int = Chat;
---functions---
geochats.createGeoChat title:string geo_point:InputGeoPoint address:string venue:string = geochats.StatedMessage;

invokeWithLayer6#3a64d54d {X:Type} query:!X = X;

Layer 5

Added parameters for internationalization.

Schema changes

• Added parameter lang_code to methods auth.sendCode, account.registerDevice

Schema

---functions---
auth.sendCode phone_number:string sms_type:int api_id:int api_hash:string lang_code:string = auth.SentCode;
account.registerDevice token_type:int token:string device_model:string system_version:string app_version:string app_sandbox:Bool lang_code:string = Bool;

invokeWithLayer5#417a57ae {X:Type} query:!X = X;

Layer 4

Added geochats. More…

Schema changes

• Added many constructors and methods for geochats.
• Added friends_unread_count field to constructor updates.state.

Schema

inputGeoChat chat_id:int access_hash:long = InputGeoChat;

geoChat id:int access_hash:long title:string address:string geo:GeoPoint photo:ChatPhoto participants_count:int date:int left:Bool version:int = Chat;

geoChatMessageEmpty chat_id:int id:int = GeoChatMessage;
geoChatMessage chat_id:int id:int from_id:int date:int message:string media:MessageMedia = GeoChatMessage;
geoChatMessageService chat_id:int id:int from_id:int date:int action:MessageAction = GeoChatMessage;

geochats.statedMessage message:GeoChatMessage chats:Vector<Chat> users:Vector<User> seq:int = geochats.StatedMessage;

geochats.located results:Vector<ChatLocated> messages:Vector<GeoChatMessage> chats:Vector<Chat> users:Vector<User> = geochats.Located;

geochats.messages messages:Vector<GeoChatMessage> chats:Vector<Chat> users:Vector<User> = geochats.Messages;
geochats.messagesSlice count:int messages:Vector<GeoChatMessage> chats:Vector<Chat> users:Vector<User> = geochats.Messages;

messageActionGeoChatCreate title:string address:string = MessageAction;
messageActionGeoChatCheckin = MessageAction;
updateNewGeoChatMessage message:GeoChatMessage = Update;
updates.state pts:int date:int seq:int unread_count:int friends_unread_count:int = updates.State;

---functions---

geochats.getLocated geo_point:InputGeoPoint radius:int limit:int = geochats.Located;
geochats.checkin peer:InputGeoChat = geochats.StatedMessage;
geochats.getFullChat peer:InputGeoChat = messages.ChatFull;
geochats.editChatTitle peer:InputGeoChat title:string address:string = geochats.StatedMessage;
geochats.editChatPhoto peer:InputGeoChat photo:InputChatPhoto = geochats.StatedMessage;
geochats.search peer:InputGeoChat q:string filter:MessagesFilter min_date:int max_date:int offset:int max_id:int limit:int = geochats.Messages;
geochats.getHistory peer:InputGeoChat offset:int max_id:int limit:int = geochats.Messages;
geochats.setTyping peer:InputGeoChat typing:Bool = Bool;
geochats.sendMessage peer:InputGeoChat message:string random_id:long = geochats.StatedMessage;
geochats.sendMedia peer:InputGeoChat media:InputMedia random_id:long = geochats.StatedMessage;
geochats.createGeoChat title:string geo_point:InputGeoPoint address:string = geochats.StatedMessage;

invokeWithLayer4#dea0d430 {X:Type} query:!X = X;

PUSH-notifications

• Added notification of GEOCHAT_CHECKIN type — a user has checked-in in a geochat.

Layer 3

Support for link changes for a contact when a message is sent. Now, if user X has user Y in the contact list and if user Y writes a message to user X, number X will become available for him. More…

Schema changes

• Added constructors messages.statedMessagesLinks, messages.statedMessageLink, messages.sentMessageLink. They are completely similar to previous ones except for the links field containing changed links.
• Added events_mask field to constructors inputPeerNotifySettings, peerNotifySettings making possible turning-off PUSH-notifications on image changes.
• Added method messages.forwardMessage for sending single messages.
• Added method messages.sendBroadcast for bulky messaging.

Schema

messages.statedMessagesLinks messages:Vector<Message> chats:Vector<Chat> users:Vector<User> links:Vector<contacts.Link> pts:int seq:int = messages.StatedMessages;
messages.statedMessageLink message:Message chats:Vector<Chat> users:Vector<User> links:Vector<contacts.Link> pts:int seq:int = messages.StatedMessage;
messages.sentMessageLink id:int date:int pts:int seq:int links:Vector<contacts.Link> = messages.SentMessage;

---functions---

messages.forwardMessage peer:InputPeer id:int random_id:long = messages.StatedMessage;
messages.sendBroadcast contacts:Vector<InputUser> message:string media:InputMedia = messages.StatedMessages;

invokeWithLayer3#b7475268 {X:Type} query:!X = X;

Layer 2

Support for notifications on changes of contact profile images. It is assumed that receiving such image changed notification a client will add a record on this event in the message history with this contact.

Schema changes

• Added date and previous fields to constructor updateUserPhoto.
• Added events_mask field to constructors inputPeerNotifySettings, peerNotifySettings making possible turning-off PUSH-notifications on image change.
• Added identifier for relevant image to constructor userProfilePhoto.
• Added method photos.getUserPhotos to get a history of previous profile images.

Schema

inputPeerNotifySettings mute_until:int sound:string show_previews:Bool events_mask:int = InputPeerNotifySettings;
peerNotifySettings mute_until:int sound:string show_previews:Bool events_mask:int = PeerNotifySettings;
updateUserPhoto user_id:int date:int photo:UserProfilePhoto previous:Bool = Update;
userProfilePhoto photo_id:long photo_small:FileLocation photo_big:FileLocation = UserProfilePhoto;

---functions---

photos.getUserPhotos user_id:InputUser offset:int max_id:int limit:int = photos.Photos;

invokeWithLayer2#289dd1f6 {X:Type} query:!X = X;

PUSH-notifications

• Added notification of CONTACT_PHOTO type — a contact has changed profile image.