sometimesattachments, stickers and GIFs
upload permission, permission to send an asset and permission to download received content are separate checks.
upload flow
create an upload with actor, purpose, filename, content_type and size. purpose is attachment, sticker, avatar, banner or group_icon. the server reserves quota, returns an upload ID and part count, and accepts raw bytes through authenticated PUT requests. parts are 10 MiB except the last. complete with ordered part numbers and their returned ETags. exact length, actual media signature, ownership, grant and scope are checked before committing. expiry is 15 minutes. cancellation and failure free concurrent upload slots and clean orphaned bytes; reserved bytes still count toward the rolling 24-hour upload budget. arbitrary URL ingestion is not supported.
asset and content types
Asset is {id,purpose,owner_kind,content_type,size,filename,width,height,status,created_at}; status is uploading, ready or failed. attachments allow the app’s supported image/video types plus application/octet-stream, with a maximum 150 MiB. unknown file types download as attachments with nosniff and safe filenames. stickers allow PNG, JPEG, GIF and WebP up to 20 MiB. avatars, banners and group icons accept validated image assets; avatar/icon maximum 5 MiB, banner maximum 20 MiB, maximum decoded area 40 megapixels. profile writes reference ready assets of the correct purpose; assets never become bearer access to an entire library.
upload and send routes
upload grants depend on purpose: attachment 35/56, bot sticker 32, user-library sticker 25, profile assets 20, group icon 41/65. chat-bound uploads include chat_id. attaching an asset requires the same installation and actor that uploaded it; user-owned uploaded stickers are selected through the sendable library instead.
scroll the table horizontally to see all columns.
| method and path | request | result |
|---|---|---|
| POST /uploads | actor, purpose, chat_id?, filename, content_type, size | 201 {id,part_size,part_count,expires_at} |
| PUT /uploads/{id}/parts/{number} | raw bytes; Content-Length; installation context | {part_number,etag} |
| POST /uploads/{id}/complete | parts:[{part_number,etag}] | 201 Asset |
| DELETE /uploads/{id} | none | 204; cancel/reservation cleanup |
| POST /chats/{chat}/attachments | actor, asset_id, caption?:string | 201 Message; permission 35/56 |
| GET /chats/{chat}/attachments/{id}/content | optional single Range header | bytes; permission 11 + readable containing message |
| GET /stickers/sendable | actor, cursor, limit | eligible Sticker list; permission 32/53 |
| POST /chats/{chat}/stickers | actor, sticker_id or ready asset_id | 201 Message; permission 32/53 |
| GET /gifs/search | actor, q:1–100 chars, cursor, limit | resolved Gif list; permission 33/54 |
| POST /chats/{chat}/gifs | actor, gif_id | 201 Message; permission 33/54 |
| GET /me/stickers | cursor, limit | Sticker list; permission 25 |
| POST /me/stickers | ready sticker asset_id, name:1–40 chars | 201 Sticker; permission 25 |
| DELETE /me/stickers/{id} | If-Match | 204; permission 25; remove library association |
sticker ownership
Sticker is {id,name,owner_id,uploaded,content_type,size,thumbnail_url,revision}; sendable views provide an authenticated thumbnail route restricted to that purpose. as a bot, the bot can send any sticker currently in the installer’s library, including adopted stickers, or upload its own application-owned sticker. as you, it can select only stickers uploaded by the installer and still in that library. sticker-library management consumes the user’s existing quota of 25 active uploaded stickers and cannot bypass uploaded ownership by adopting a bot asset. deleting a library association does not erase copies retained by existing messages or other users.
download access and GIF sources
attachment content is streamed through an authenticated authorization check, including range requests; no permanent public signed URL bypasses revocation. thumbnail and profile-asset routes use equivalent audience-aware checks. Gif is {id,provider,width,height,preview_url,expires_at}; only server-resolved supported-provider IDs are accepted for sends, with their existing moderation rules. provider preview URLs are public catalogue media, never private attachment URLs. uploaded bot stickers count against an application quota of 100 assets and 200 MiB, separately from the installer’s quota.