Telegram Bot API: Отправить файл и скачать файл от пользователя

Сценарий из mcp-everything. Актуально на 2026-10-24.

Прислать счёт или отчёт документом, принять от пользователя фото или файл.

1. Отправь файл с диска: POST /bot{token}/sendDocument в формате multipart/form-data с chat_id и document. Бот может отправлять файлы до 50 МБ. Фото — POST /bot{token}/sendPhoto: можно передать HTTP-ссылку вместо загрузки.
2. Telegram вернёт file_id: повторно отправляй тот же файл по нему, без загрузки.
3. Чтобы скачать файл от пользователя, возьми file_id из сообщения (document.file_id или последний элемент photo) и вызови POST /bot{token}/getFile.
4. Скачай файл по адресу https://api.telegram.org/file/bot<токен>/ из ответа. Ссылка живёт не меньше часа, через облачный Bot API скачиваются файлы до 20 МБ.

# Отправить PDF
curl -X POST "https://api.telegram.org/bot$TOKEN/sendDocument" \
  -F chat_id=123456789 \
  -F document=@invoice-1042.pdf \
  -F caption='Счёт по заказу №1042'

# Получить путь к файлу пользователя и скачать
FILE_PATH=$(curl -s -X POST "https://api.telegram.org/bot$TOKEN/getFile" -d file_id='<file_id>' | jq -r .result.file_path)
curl -o file.bin "https://api.telegram.org/file/bot$TOKEN/$FILE_PATH"

Базовые URL

• Боевой: https://api.telegram.org
• URL метода: https://api.telegram.org/bot<token>/METHOD_NAME

Авторизация

Тип: API-ключ

Токен бота (выдаёт @BotFather) передаётся в пути запроса после bot.

https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/getMe

Методы сценария

POST /bot{token}/sendPhoto — Отправка фото

Параметр	Где	Тип	Обяз.	Описание
token	path	string	да	Токен бота
chat_id	body	integer/string	да	ID чата или @username
photo	body	file/string	да	file_id, HTTP URL или загрузка через multipart/form-data
caption	body	string	нет	Подпись, 0–1024 символа
parse_mode	body	string	нет	Режим форматирования подписи
has_spoiler	body	boolean	нет	Скрыть фото под спойлером
show_caption_above_media	body	boolean	нет	Подпись над медиа
reply_markup	body	object	нет	Клавиатура

POST /bot{token}/sendDocument — Отправка файла

Боты могут отправлять файлы любого типа до 50 МБ.

Параметр	Где	Тип	Обяз.	Описание
token	path	string	да	Токен бота
chat_id	body	integer/string	да	ID чата или @username
document	body	file/string	да	file_id, HTTP URL или загрузка через multipart/form-data
thumbnail	body	file/string	нет	Превью в JPEG до 200 кБ
caption	body	string	нет	Подпись, 0–1024 символа
parse_mode	body	string	нет	Режим форматирования подписи
disable_content_type_detection	body	boolean	нет	Отключить определение типа файла на сервере
reply_markup	body	object	нет	Клавиатура

POST /bot{token}/getFile — Информация о файле для скачивания

Возвращает объект File; ссылка https://api.telegram.org/file/bot<token>/<file_path> действует не меньше часа. Боты могут скачивать файлы до 20 МБ.

Параметр	Где	Тип	Обяз.	Описание
token	path	string	да	Токен бота
file_id	body	string	да	Идентификатор файла

Нюансы

• Поддерживаются GET и POST; параметры — строкой запроса, application/x-www-form-urlencoded, application/json (кроме загрузки файлов) или multipart/form-data (для файлов).
• Имена методов нечувствительны к регистру; все запросы — в UTF-8 и только по HTTPS.
• Ответ — JSON с полем ok; при успехе результат в result, при ошибке — description и error_code.
• getUpdates и вебхук взаимоисключающие: пока вебхук установлен, getUpdates не работает. Порты вебхука: 443, 80, 88, 8443.
• Чтобы не получать дубли при long polling, пересчитывайте offset после каждого ответа.
• ID чатов могут превышать 32 бита (до 52 значимых бит) — храните их в 64-битных целых.
• allow_paid_broadcast снимает лимиты рассылки до 1000 сообщений в секунду за 0,1 Telegram Stars за сообщение.

Другие сценарии

• Отправлять уведомления в чат или канал
• Принимать сообщения через вебхук
• Бот без своего сервера с HTTPS: long polling
• Кнопки под сообщением и обработка нажатий

---

Если этого недостаточно — официальная документация: https://core.telegram.org/bots/api Вся интеграция одним документом: https://mcp-everything.ru/integrations/telegram-bot-api.md