# 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<токен>/<file_path> из ответа. Ссылка живёт не меньше часа, через облачный Bot API скачиваются файлы до 20 МБ.

```bash
# Отправить 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://mcp-everything.ru/integrations/telegram-bot-api/scenarios/otpravlyat-uvedomleniya-v-chat-ili-kanal.md)
- [Принимать сообщения через вебхук](https://mcp-everything.ru/integrations/telegram-bot-api/scenarios/prinimat-soobscheniya-cherez-vebhuk.md)
- [Бот без своего сервера с HTTPS: long polling](https://mcp-everything.ru/integrations/telegram-bot-api/scenarios/bot-bez-svoego-servera-s-https-long.md)
- [Кнопки под сообщением и обработка нажатий](https://mcp-everything.ru/integrations/telegram-bot-api/scenarios/knopki-pod-soobscheniem-i-obrabotka.md)

---

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