On startup, clients should fetch the animated emoji stickerset by calling the messages.getStickerSet method, providing inputStickerSetAnimatedEmoji to the stickerset field.
+The returned stickerset will contain a set of animated stickers, one for each of the supported emojis.
+
Clients should substitute messages containing only one instance of one of the allowed emojis with the respective animated sticker.
+
Animated emojis should loop only once when first sent or received, or when clicked.
+
For special dice emojis like , , or , clients are supposed to behave differently both when sending and receiving such emojis: click here for more info ».
+
Emojis with sounds
+
Certained animated emojis should play sound when clicked, as specified by server-side configuration.
+
The returned JSON object will contain the following map, with a list of file IDs to download:
When working with the API, it is sometimes necessary to send a relatively large file to the server. For example, when sending a message with a photo/video attachment or when setting the current user’s profile picture.
+
Uploading files
+
There are a number of API methods to save files. The schema of the types and methods used is presented below:
Before transmitting the contents of the file itself, the file has to be assigned a unique 64-bit client identifier: file_id.
+
The file’s binary content is then split into parts. All parts must have the same size ( part_size ) and the following conditions must be met:
+
+
part_size % 1024 = 0 (divisible by 1KB)
+
524288 % part_size = 0 (512KB must be evenly divisible by part_size)
+
+
The last part does not have to satisfy these conditions, provided its size is less than part_size.
+
Each part should have a sequence number, file_part, with a value ranging from 0 to 2,999.
+
After the file has been partitioned you need to choose a method for saving it on the server. Use upload.saveBigFilePart in case the full size of the file is more than 10 MB and upload.saveFilePart for smaller files.
+
Each call saves a portion of the data in a temporary location on the server to be used later. The storage life of each portion of data is between several minutes and several hours (depending on how busy the storage area is). After this time, the file part will become unavailable. To increase the time efficiency of a file save operation, we recommend using a call queue, so X pieces of the file are being saved at any given moment in time. Each successful operation to save a part invokes the method call to save the next part. The value of X can be tuned to achieve maximum performance.
+
When using one of the methods mentioned above to save file parts, one of the following data input errors may be returned:
+
+
FILE_PARTS_INVALID - Invalid number of parts. The value is not between 1..3000
+
FILE_PART_INVALID: The file part number is invalid. The value is not between 0 and 2,999.
+
FILE_PART_TOO_BIG: The size limit (512 KB) for the content of the file part has been exceeded
+
FILE_PART_EMPTY: The file part sent is empty
+
FILE_PART_SIZE_INVALID - 512KB cannot be evenly divided by part_size
+
FILE_PART_SIZE_CHANGED - The part size is different from the size of one of the previous parts in the same file
+
+
While the parts are being uploaded, an MD5 hash of the file contents can also be computed to be used later as the md5_checksum parameter in the inputFile constructor (since it is checked only by the server, for encrypted secret chat files it must be generated from the encrypted file).
+After the entire file is successfully saved, the final method may be called and passed the generated inputFile object. In case the upload.saveBigFilePart method is used, the inputFileBig constructor must be passed, in other cases use inputFile.
messages.uploadMedia - Uploads a media file to a chat, without sending it, returning only a MessageMedia constructor that can be used to later send the file to multiple chats, without reuploading it every time.
Telegram allows grouping photos into albums and generic files (audio, docuemnts) into media groups.
+
To do this, messages.sendMultiMedia is used, wrapping each InputMedia constructor (uploaded or pre-existing, maximum 10 per media group) into an inputSingleMedia constructor, optionally providing a custom per-file caption in message.
+
For photo albums, clients should display an album caption only if exactly one photo in the group has a caption, otherwise no album caption should be displayed, and only when viewing in detail a specific photo of the group the caption should be shown.
+Other grouped media can display a caption under each file.
For some types of documents like GIFs, messages.getDocumentByHash can be used to search for the document on Telegram servers.
+The SHA256 hash of the file is computed, and it is passed along with the file's mime type and size to the method: if the file type is correct and the file is found, a document is returned.
Animated profile pictures are also supported, by populating the video constructor: square MPEG4 videos up to 1080x1080 are supported, 800x800 is the recommended resolution.
+The video_start_ts is a floating point UNIX timestamp in seconds, indicating the frame of the video that should be used as static preview.
id, file_reference and access_hash taken from the photo constructor
+
thumb_size taken from the type field of the desired PhotoSize of the photo
+
+
+
+
For profile pictures of users, channels, supergroups and groups, since in most occasions they are encountered as simple fileLocationToBeDeprecated constructors without an associated photo, inputPeerPhotoFileLocation has to be used:
+
+
peer is the identifier of the peer whose photo we want to download
+
volume_id and local_id are extracted from the fileLocationToBeDeprecated of the desired quality (the logic for selecting the quality of profile pictures will be changed soon)
id, file_reference and access_hash taken from the document constructor
+
If downloading the thumbnail of a document, thumb_size should be taken from the type field of the desired PhotoSize of the photo; otherwise, provide an empty string.
For previews of sticker sets, inputStickerSetThumb is used (note: to download stickers and previews of stickers use the document method described above):
volume_id and local_id are extracted from the fileLocationToBeDeprecated from the thumbPhotoSize of the StickerSet (the logic for downloading stickerset previews will be changed soon)
+
+
+
+
For old deprecated photos, if the client has cached some old fileLocations with the deprecatedsecret identifier, inputFileLocation is used (this is mainly used for backwards compatiblity with bot API file IDs, all user clients must use the modern inputPhotoFileLocation file IDs):
+
+
All fields are taken from the previously cached fileLocation except for id, file_reference and access_hash taken from the photo constructor
+
+
+
+
The size of each file in bytes is available, which makes it possible to download the file in parts using the parameters offset and limit, similar to the way files are uploaded.
+
If precise flag is not specified, then
+
+
The parameter offset must be divisible by 4 KB.
+
The parameter limit must be divisible by 4 KB.
+
1048576 (1 MB) must be divisible by limit.
+
+
If precise is specified, then
+
+
The parameter offset must be divisible by 1 KB.
+
The parameter limit must be divisible by 1 KB.
+
limit must not exceed 1048576 (1 MB).
+
+
In any case the requested part should be within one 1 MB chunk from the beginning of the file, i. e.
The file download operation may return a FILE_REFERENCE_EXPIRED error (or another error starting with FILE_REFERENCE_): in this case, the file_reference field of the input location must be refreshed.
+The file download operation may return an upload.fileCdnRedirect constructor: in this case, these instructions must be followed for downloading CDN files.
+The file download operation may also return one of the following data input errors:
+
+
FILE_ID_INVALID: The file address is invalid
+
OFFSET_INVALID: The offset value is invalid
+
LIMIT_INVALID: The limit value is invalid
+
FILE_MIGRATE_X: The file is in the datacenter No. X
In order to confirm the integrity of the downloaded file, clients are recommended to verify hashes for each downloaded part, as for CDN DCs.
+upload.getFileHashes contain FileHash constructors. Each of these constructors contains the SHA-256 hash of a part of the file that starts with offset and takes limit bytes.
+
Before saving each portion of the data received from the DC into the file, the client can confirm that its hash matches the hash that was received from the master DC. If missing a hash for any file part, client developers must use the upload.getFileHashes method to obtain the missing hash.
Telegram attaches a vector of thumbnails with reduced resolution to all uploaded media.
+The server also generates a trimmed and scaled down video preview for videos, GIFs and animated profile pictures.
+
Image thumbnail types
+
Each photo preview has a specific type, indicating the resolution and image transform that was applied server-side.
A photoStrippedSize (with type i) is an extremely low-res thumbnail, embedded directly inside media location objects.
+It should be shown to the user in chat message previews, or while still downloading the most appropriately sized photoSize through the media DCs as described above.
+
The stripped bytes payload should be inflated to a JPG payload as seen here ».
Messages with animated stickers can have a compressed svg (< 300 bytes) to show the outline of the sticker before fetching the actual lottie animation.
+Animated sticker outlines will have a j type photoPathSize thumbnail.
+
This specific vector thumbnail consists in an SVG path, specially encoded to save space.
+This path will be the outline of the animated sticker, and should be shown to the user while downloading the actual sticker.
+
As for stripped sizes, the payload should be inflated using the following algorithm:
A videoSize constructor is typically used for [animated profile pictures]() and video previews.
+
+
+
+
Type
+
Description
+
Format
+
+
+
+
+
u
+
Animated profile picture
+
MPEG4
+
+
+
v
+
Video preview
+
MPEG4
+
+
+
+
Downloading webfiles
+
Remote HTTP files sent by inline bots in response to inline queries and in other places are represented by WebDocument constructors.
+When forwarding such remote HTTP files, they should be sent using external InputMedia constructors.
+Remote HTTP files can only be downloaded directly by the client if contained in a webDocumentNoProxy constructor: in this case, the file is deemed safe to download (this is the case for HTTPS files from certain trusted domains).
+
However, if the remote file is contained in a webDocument, to avoid leaking sensitive information the file must be downloaded through telegram's servers.
+This can be done in a manner similar to normal files, with the difference that upload.getWebFile must be used, instead.
w - Map width in pixels before applying scale; 16-1024
+
h - Map height in pixels before applying scale; 16-1024
+
zoom - Map zoom level; 13-20
+
scale - Map scale; 1-3
+
+
+
+
General Considerations
+
It is recommended that large queries (upload.getFile, upload.saveFilePart, upload.getWebFile) be handled through a separate session and a separate connection, in which no methods other than these should be executed. If this is done, then data transfer will cause less interference with getting updates and other method calls.
, 
, or 
, clients are supposed to behave differently both when sending and receiving such emojis: