Files & media

When to use

Sending images, files, or video requires a registered file_id before send*.

Steps

1. POST /api/v1/bots/files/upload-credentials (required: fileName, fileSize, checksum).
2. If the response has uploadRequired: true (or omits the flag), PUT the object using returned uploadUrl / headers.
3. POST /api/v1/bots/files/complete (checksum required again) → file_id.
4. Call sendPhoto / sendDocument / … with optional caption and reply_to_message_id.

Content reuse (skip upload)

Always send a full-file checksum, and prefer a stable reuseRequestId (same across retries of one logical upload; new value for a different upload). On a trusted hit the server reuses the physical blob, creates a new logical File, and returns uploadRequired: false with file / file_id—skip PUT and complete. reuseExisting is a legacy compat flag and may be omitted.

• Each business send gets its own logical file_id; SDKs do not cache old file_id across messages.
• Raw HTTP participates in reuse when checksum + reuseRequestId are present; Node helpers like sendPhotoFromFile compute checksum and send an idempotency key automatically.
• If the response includes possessionRequired / possessionChallenge, complete the challenge before continuing.
• Legacy client MediaUploadCache is deprecated and a no-op—use server-side reuse instead.

Example

curl -X POST "$API/bots/files/upload-credentials" \
  -H "Authorization: Bearer $SOCHAT_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "fileName": "photo.jpg",
  "fileSize": 12345,
  "fileType": "image/jpeg",
  "checksum": "<64-char-sha256-hex>",
  "reuseRequestId": "upload-<stable-uuid>"
}'

curl -X POST "$API/bots/sendPhoto" \
  -H "Authorization: Bearer $SOCHAT_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chat_id":"<chat_id>","file_id":"<file_id>","caption":"Hello"}'

Limits & errors

• checksum is required on both upload-credentials and complete (64-char SHA-256 hex).
• Inspect metadata with getFile.

Next

Files API · Send APIs.