The short answer
- 1Up to 10 MB use saveFilePart; above that saveBigFilePart, in parts.
- 2Parts are multiples of 1 KB that divide 512 KB evenly.
- 3Download with getFile: multiples of 4 KB, never crossing a 1 MB boundary.
In this article
Files move in parts
In the Telegram API a file is never sent in one go. You upload it in parts, and you download it part by part, choosing a position (offset) and a length (limit) each time. The official apps and TDLib do this for you; if you implement it yourself, the server only accepts parts that follow the size rules below.
Uploading a file in parts
| File size | Method | Passed at the end |
|---|---|---|
| Up to 10 MB | upload.saveFilePart | inputFile |
| Over 10 MB | upload.saveBigFilePart | inputFileBig |
- Pick a random 64-bit number of your own as the file's ID (
file_id). - Choose a part size. It must be a multiple of 1 KB, and 512 KB must be divisible by it (512 KB, 256 KB, 128 KB and so on). Only the last part may be smaller.
- Upload the parts in order, numbering them from 0. The maximum number of parts comes from a server configuration value, and it differs between ordinary and Premium accounts.
- When every part is up, put that file ID in
inputFile(orinputFileBig) and pass it to a request such as sending a message. For small files you can include the MD5 so the server can detect corruption.
An uploaded file can be downloaded straight away only from the data center it was uploaded to. To get it elsewhere, follow the FILE_MIGRATE error; see data centers and _MIGRATE errors.
Downloading with upload.getFile
| Mode | Rules for offset and limit |
|---|---|
| Default | Both multiples of 4 KB, and 1 MB must be divisible by limit |
precise on | Both multiples of 1 KB, with limit up to 1 MB |
| Both | The requested range must not cross a 1 MB boundary |
Large files download faster over several separate connections. Set those connections not to receive updates; see layers and initConnection. For popular files the server may redirect you to a CDN; download from the CDN data center it names, and verify the hashes of the parts you receive.
Errors you will meet
| Error | What to do |
|---|---|
FILE_MIGRATE_X | Download from data center X |
FILE_REFERENCE_EXPIRED | The file reference has expired; fetch the original message again for a fresh one. See expired file references |
FLOOD_WAIT_X | Wait X seconds; see reading API errors |
Sending files through the Bot API needs none of these part rules: you upload over HTTP or reuse a file_id, but the Bot API has its own size limits.
FAQ
When should I use saveBigFilePart?
For files larger than 10 MB. Smaller files use saveFilePart.
What part size can I use for Telegram uploads?
A multiple of 1 KB that divides 512 KB evenly, such as 512 KB or 256 KB; only the last part may be smaller.
Why does getFile reject my offset?
In default mode offset and limit must be multiples of 4 KB and the range must not cross a 1 MB boundary.
Sources
At a glance
- 1Upload
Random 64-bit file ID, numbered parts, then inputFile or inputFileBig.
- 2Download
offset and limit rules; precise mode allows 1 KB steps.
- 3Errors
FILE_MIGRATE, FILE_REFERENCE_EXPIRED, FLOOD_WAIT.
Updated
