Media and getFile

Bots send files with sendPhoto, sendVideo and sendDocument, and download files they receive with getFile. Files go through the same pipeline as people's: location data and camera details are stripped from pictures.

Sending a file#

Upload the file with multipart/form-data under the method's own field name, or reuse a file_id your bot received or sent:

curl -s https://bots.qivuna.com/v1/sendPhoto \
  -H "Authorization: Bot $QIVUNA_BOT_TOKEN" \
  -F chat_id=-4503600130020245 \
  -F photo=@chart.png \
  -F caption="Weekly results"

{"chat_id": -4503600130020245, "photo": "3f9c0a7e4b1d2c5e6f708192a3b4c5d6e7f80912"}

• One file per message, at most 20 MB (413 payload_too_large). The other form fields together stay under 1 MB.
• The type is decided from the file's bytes, not its name or the declared type. A file that does not fit the method answers 400 bad_request naming the field. File names have direction and invisible characters removed, and pass the content rules.
• caption up to 1,024 characters, with caption_entities (or entities) or parse_mode: "HTML". reply_markup, reply_to_message_id, disable_notification and protect_content work as in sendMessage.
• A file_id sent again is copied: the new message has its own file, and it counts toward the daily upload volume again. An unknown file_id answers 400 bad_request.
• Only these three methods take files; a file sent to any other method answers 413.

Where media can go#

• Groups: the grant needs can_send_media (and can_send for a caption), and the group must allow members to send media.
• Channels: can_post and can_send_media.
• 1:1 chats with plain bots: as sendMessage (started, not stopped, unsolicited cap).
• Not in encrypted bots' private chats (403 e2ee_required) or encrypted groups (403 e2ee_unsupported): files are not part of encrypted bot messages in v1.

Every refusal happens before anything is stored or counted.

Upload limits#

Past the volume, 429 rate_limited with retry_after until the next UTC midnight. Pictures are decoded one at a time per bot, in a pool shared by bots; when it is busy you get 429 with a short retry_after — retry then.

Files your bot receives#

A message with files carries the first one as photo, video or document (by its stored type) — a single File, not a list of sizes — and its text as caption. People can send up to 10 files in one message; then attachments lists all of them in order, each as {type, …File}.

"photo": {"file_id": "3f9c0a7e4b1d2c5e6f708192a3b4c5d6e7f80912",
          "file_unique_id": "Qm7bX0k2_Lr9TzP1",
          "file_size": 248113, "mime_type": "image/jpeg", "file_name": "IMG_2041.jpg"}

End-to-end encrypted files are never presented to bots.

Downloading with getFile#

curl -s "https://bots.qivuna.com/v1/getFile?file_id=3f9c0a7e4b1d2c5e6f708192a3b4c5d6e7f80912" \
  -H "Authorization: Bot $QIVUNA_BOT_TOKEN"
# → {"ok":true,"result":{"file_id":"3f9c…","file_unique_id":"Qm7b…","file_size":248113,
#     "mime_type":"image/jpeg","file_name":"IMG_2041.jpg","file_path":"<43 characters>"}}

curl -s -o photo.jpg "https://bots.qivuna.com/v1/file/<file_path>" \
  -H "Authorization: Bot $QIVUNA_BOT_TOKEN"

• The download needs the same bot's Authorization header; the link alone opens nothing, and it lasts 1 hour.
• Each download is checked again: the message still exists and is not deleted or expired, and your bot is still in that room (or a party to that 1:1 chat). Otherwise 404 file_not_found.
• A file_id is valid for your bot only, for at most 30 days. file_unique_id stays the same for the same file across the bots of your id namespace and cannot be linked across developers.
• Downloads are served with Cache-Control: private, no-store. Store what you need yourself, and delete it when you no longer need it.