Отправка файлов в Telegram Bot API на PHP: cURL, file_id, URL и лимиты размера

В процессе разработки Telegram-ботов для бизнеса регулярно возникает необходимость отправлять пользователям медиаконтент: счета в PDF, чеки, фотографии товаров, актов или выгрузки отчётов. Telegram Bot API предоставляет три основных способа передачи файлов в методах sendPhoto, sendDocument, sendVideo и других: бинарная загрузка через multipart/form-data, передача file_id ранее загруженного объекта и передача прямой HTTP-ссылки.

Каждый из этих подходов имеет свои лимиты, подводные камни по производительности и сценарии применения. В этой статье мы подробно разберем реализацию всех трех способов на чистом PHP с использованием cURL, научимся кэшировать file_id и правильно обрабатывать ошибки API.

Способы передачи файлов и лимиты Telegram Bot API

Перед тем как писать код, важно чётко понимать технические ограничения Telegram Bot API. Выбор неверного способа передачи может привести к ошибкам 400 BAD_REQUEST или существенным задержкам при отклике бота.

  • Прямая загрузка (multipart/form-data): позволяет загружать файлы с вашего сервера. Лимит на размер файла для обычного Bot API составляет 50 МБ для документов и 10 МБ для фотографий. Если используется собственный экземпляр Local Bot API Server, этот лимит увеличивается до 2000 МБ (2 ГБ).
  • Передача file_id: самый быстрый и экономный способ. Файл уже находится на серверах Telegram, поэтому передаётся только короткий текстовый идентификатор. Лимит по размеру ограничен лишь исходным файлом (до 2 ГБ). Отправка происходит мгновенно и не расходует входящий/исходящий трафик вашего сервера.
  • Передача публичного URL: Telegram самостоятельно скачивает файл по вашей HTTP/HTTPS ссылке. Однако здесь действуют самые жесткие лимиты: максимальный размер файла для скачивания Telegram по URL составляет 20 МБ для документов и 5 МБ для фото. Кроме того, сервер Telegram должен иметь прямой доступ к файлу без капч, базовой авторизации и с валидным SSL-сертификатом.

Загрузка локального файла через multipart/form-data на cURL

Когда файл генерируется «на лету» (например, PDF-счёт через Dompdf или TCPDF) или загружается клиентом из админки, его необходимо передать в Telegram первичной загрузкой. Для этого сформируем запрос multipart/form-data с помощью класса CURLFile.

Использование file_get_contents() для выполнения запросов к Telegram API недопустимо по нескольким причинам: невозможность гибкой настройки таймаутов, отсутствие нормального считывания HTTP-статусов при ошибках 4xx/5xx и проблемы с передачей бинарных данных большой длины.

<?php

/**
* Отправка локального документа в Telegram через multipart/form-data
*
* @param string $chatId Идентификатор чата получателя
* @param string $filePath Абсолютный путь к файлу на сервере
* @param string $caption Подпись к файлу (опционально)
* @return array Массив result из ответа Telegram API
* @throws RuntimeException При ошибках cURL или Telegram API
*/
function sendTelegramDocument(string $chatId, string $filePath, string $caption = ''): array
{
$token = getenv('TELEGRAM_BOT_TOKEN');
if (!$token) {
throw new RuntimeException('Переменная окружения TELEGRAM_BOT_TOKEN не задана');
}

if (!file_exists($filePath) || !is_readable($filePath)) {
throw new InvalidArgumentException("Файл не найден или недоступен для чтения: {$filePath}");
}

$mimeType = mime_content_type($filePath) ?: 'application/octet-stream';

$postData = [
'chat_id' => $chatId,
'document' => new CURLFile($filePath, $mimeType, basename($filePath)),
'caption' => $caption,
'parse_mode' => 'HTML',
];

$url = "https://api.telegram.org/bot{$token}/sendDocument";

$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $postData,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
CURLOPT_CONNECTTIMEOUT => 10,
]);

$response = curl_exec($ch);
$curlError = curl_error($ch);
$httpCode = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($response === false) {
throw new RuntimeException("cURL ошибка при отправке файла: {$curlError}");
}

$data = json_decode($response, true);
if (json_last_error() !== JSON_ERROR_NONE) {
throw new RuntimeException('Ошибка парсинга JSON ответа Telegram API: ' . json_last_error_msg());
}

if ($httpCode !== 200 || empty($data['ok'])) {
$description = $data['description'] ?? 'Неизвестная ошибка';
$errorCode = $data['error_code'] ?? $httpCode;
throw new RuntimeException("Telegram API Error [{$errorCode}]: {$description}");
}

return $data['result'];
}

Повторное использование file_id для ускорения отправки

Повторно отправлять один и тот же файл (например, публичную оферту, прайс-лист или инструкцию) через multipart/form-data при каждом обращении пользователя — распространённая архитектурная ошибка. Это нагружает сеть, замедляет работу бота и упирается в лимиты пропускной способности.

При первой отправке документа или фотографии Telegram возвращает в объекте ответа уникальный file_id. Сохранив этот file_id в базу данных, все последующие отправки данного документа можно выполнять через обычный JSON-запрос без повторной загрузки бинарного содержимого.

Сначала напишем универсальную функцию для отправки медиа по file_id или URL через JSON-нагрузку:

<?php

/**
* Отправка медиафайла по file_id или URL через application/json
*
* @param string $method Метод API (sendPhoto, sendDocument и т.д.)
* @param string $chatId Идентификатор чата
* @param string $fileIdentifier Уникальный file_id или публичный URL
* @param string $caption Подпись к медиа
* @return array Результат запроса
*/
function sendTelegramMediaByIdOrUrl(string $method, string $chatId, string $fileIdentifier, string $caption = ''): array
{
$token = getenv('TELEGRAM_BOT_TOKEN');
if (!$token) {
throw new RuntimeException('Переменная TELEGRAM_BOT_TOKEN не задана');
}

$paramName = ($method === 'sendPhoto') ? 'photo' : 'document';

$payload = [
'chat_id' => $chatId,
$paramName => $fileIdentifier,
'caption' => $caption,
'parse_mode' => 'HTML',
];

$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => "https://api.telegram.org/bot{$token}/{$method}",
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
CURLOPT_CONNECTTIMEOUT => 5,
]);

$response = curl_exec($ch);
$curlError = curl_error($ch);
$httpCode = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($response === false) {
throw new RuntimeException("cURL ошибка: {$curlError}");
}

$data = json_decode($response, true);
if (json_last_error() !== JSON_ERROR_NONE || $httpCode !== 200 || empty($data['ok'])) {
$desc = $data['description'] ?? $curlError ?? 'HTTP ' . $httpCode;
throw new RuntimeException("Ошибка отправки по file_id/URL: {$desc}");
}

return $data['result'];
}

Теперь организуем гибридную логику: проверяем наличие сохранённого file_id в базе данных. Если он есть — отправляем моментально. Если его нет или Telegram вернул ошибку (например, file_id стал недействителен при смене бота), выполняем первичную загрузку файла и сохраняем свежий file_id в БД.

<?php

/**
* Гибридная отправка документа с кэшированием file_id в MySQL/PostgreSQL
*/
function sendPriceList(PDO $db, string $chatId, string $localFilePath, string $documentKey): string
{
// 1. Пытаемся достать file_id из БД
$stmt = $db->prepare('SELECT file_id FROM telegram_files WHERE document_key = :key LIMIT 1');
$stmt->execute([':key' => $documentKey]);
$cachedFileId = $stmt->fetchColumn();

if ($cachedFileId) {
try {
sendTelegramMediaByIdOrUrl('sendDocument', $chatId, $cachedFileId, 'Актуальный прайс-лист');
return $cachedFileId;
} catch (RuntimeException $e) {
// Фолбэк: если file_id устарел или сброшен, переходим к загрузке файла
}
}

// 2. Первичная загрузка через multipart/form-data
$result = sendTelegramDocument($chatId, $localFilePath, 'Актуальный прайс-лист');
$newFileId = $result['document']['file_id'];

// 3. Сохраняем полученный file_id в базу для последующих пользователей
$saveStmt = $db->prepare('
INSERT INTO telegram_files (document_key, file_id, created_at)
VALUES (:key, :file_id, NOW())
ON DUPLICATE KEY UPDATE file_id = VALUES(file_id)
');
$saveStmt->execute([
':key' => $documentKey,
':file_id' => $newFileId,
]);

return $newFileId;
}

Отправка файла по URL: когда это удобно и какие есть риски

Передача внешнего URL оправдана, если файлы уже хранятся на CDN или в S3-совместимом хранилище (Selectel, MinIO, AWS S3), и вы не хотите сначала выкачивать их на свой PHP-сервер для переотправки в Telegram.

Однако учитывайте критические риски при работе с URL:

  1. Таймауты и блокировки: Telegram скачивает файл со своих серверов. Если ваш CDN блокирует IP-диапазоны Telegram или медленно отдает контент, запрос завершится ошибкой 400 BAD_REQUEST: wrong file identifier/HTTP URL specified.
  2. Жесткий лимит 20 МБ: Если документ по ссылке превысит 20 МБ (или фото > 5 МБ), Telegram откажется его обрабатывать.
  3. Отсутствие контроля Mime-типов: Telegram определяет тип файла по HTTP-заголовку Content-Type, отдаемому вашим веб-сервером. Если CDN отдаст text/html вместо application/pdf, файл отправится с искажённым расширением.

Сравнение sendPhoto и sendDocument

Разработчики часто путают назначения методов sendPhoto и sendDocument. Главные отличия заключаются в сжатии и обработке метаданных:

  • sendPhoto: Telegram автоматически сжимает изображение, удаляет EXIF-метаданные и приводит его к оптимальному разрешению для быстрого отображения в сетке чата. Отлично подходит для каталогов товаров и превью.
  • sendDocument: Передаёт файл «как есть», без сжатия по качеству и с сохранением исходного имени файла. Идеально подходит для документов, сканов, а также фотографий в оригинальном качестве (для этого нужно передавать фото через sendDocument).

Правильный выбор метода и комбинация CURLFile с кэшированием file_id позволяют создавать надежных Telegram-ботов, способных обрабатывать тысячи медиа-запросов в минуту без перегрузки сервера.

Если вам требуется профессиональная интеграция Telegram-бота с вашей CRM, веб-сервисом или автоматизация сложных цепочек продаж, специалисты BotCreator помогут реализовать проект любой сложности.

Новые статьи — в Telegram

Разбираем, что автоматизировать в бизнесе и как это работает на практике. Без спама.