Надсилання файлів у 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: вказано неправильний ідентифікатор файлу/HTTP URL.
  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

Розбираємо, що автоматизувати в бізнесі та як це працює на практиці. Без спаму.