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 (the same value across retries of one upload and a new value for a different upload). If the response returns uploadRequired: false with file / file_id, skip PUT and complete. reuseExisting is optional and may be omitted.

• Use the file_id returned for the current upload request. Do not cache old values 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.

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.