Как описать альбом
В sendMediaGroup передают массив media из 2–10 элементов. У каждой фотографии есть type: photo и media с адресом файла. Подпись задаётся у элемента альбома; в примере она есть только у первого фото. Результат метода — массив сообщений, а не один message_id.
{
"chat_id": "YOUR_TEST_CHAT_ID",
"media": [
{
"type": "photo",
"media": "https://example.com/photos/front.jpg",
"caption": "Тестовый товар: общий вид и деталь."
},
{
"type": "photo",
"media": "https://example.com/photos/detail.jpg"
}
]
}
example.com и YOUR_TEST_CHAT_ID — placeholders: замените их своими данными. URL должен отдавать именно доступное Telegram изображение, а не HTML-страницу, форму авторизации или локальный адрес вашего компьютера. Сначала проверьте доступность тестовых изображений.
Вместо URL можно использовать file_id фотографии, ранее полученный тем же ботом. file_unique_id для отправки не подходит. Для одной фотографии используйте sendPhoto; большую подборку заранее разделите на группы допустимого размера.
Готовим локальные фотографии
Основной пример загружает два локальных JPEG, поэтому доступный из интернета сервер картинок не нужен. Требуются PHP 8.2+, cURL и fileinfo. Положите подготовленные небольшие фотографии в photos/front.jpg и photos/detail.jpg рядом со скриптами. Возьмите обычные изображения, например 1200 × 900 пикселей и менее 1 МБ каждое.
Это заранее подготовленные серверные файлы. Если путь или файл приходит от посетителя, до отправки нужны отдельная проверка загрузки, размера и типа и хранение вне публичного каталога. Не подставляйте произвольный пользовательский путь в CURLFile.
Задайте TELEGRAM_BOT_TOKEN и TELEGRAM_CHAT_ID в окружении процесса. Для личного тестового чата сначала начните диалог с ботом. .env без загрузчика не читается. Для канала отдельно проверьте право публикации.
Создаём клиент для запроса
Сохраните следующий код как telegram.php. Это общий помощник для JSON и multipart: передача массива с CURLFile включает загрузку файлов, а заголовок multipart с boundary создаёт cURL. Автоматических повторов нет.
<?php
declare(strict_types=1);
function requiredEnv(string $name): string
{
$value = getenv($name);
if ($value === false || $value === '') {
throw new RuntimeException('Не задана переменная '.$name);
}
return $value;
}
/** @param array<string, mixed> $params
* @return array<string, mixed>|list<array<string, mixed>>
*/
function telegram(string $method, array $params, bool $multipart = false): array
{
if (!preg_match('/\A[a-zA-Z]+\z/', $method)) {
throw new InvalidArgumentException('Некорректный метод');
}
$body = $multipart ? $params : json_encode($params, JSON_THROW_ON_ERROR);
$curl = curl_init('https://api.telegram.org/bot'.requiredEnv('TELEGRAM_BOT_TOKEN').'/'.$method);
if ($curl === false) {
throw new RuntimeException('Не удалось создать запрос');
}
curl_setopt_array($curl, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $body,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 60,
CURLOPT_HTTPHEADER => $multipart ? [] : ['Content-Type: application/json'],
]);
$raw = curl_exec($curl);
$status = (int) curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
if ($raw === false) {
// Не выводим URL: он содержит токен бота.
throw new RuntimeException('Сетевой сбой; результат отправки может быть неизвестен');
}
$data = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if (!is_array($data) || ($data['ok'] ?? false) !== true) {
$error = is_array($data) ? (int) ($data['error_code'] ?? 0) : 0;
$wait = is_array($data) ? ($data['parameters']['retry_after'] ?? null) : null;
throw new RuntimeException('Telegram: HTTP '.$status.', error_code '.$error
.(is_int($wait) ? ', retry_after '.$wait.' с' : ''));
}
if ($status < 200 || $status >= 300 || !is_array($data['result'] ?? null)) {
throw new RuntimeException('Неожиданный ответ; автоматический повтор отключён');
}
return $data['result'];
}
Отправляем два файла через multipart
Значение attach://photo_0 ссылается на файловое поле photo_0 того же запроса. Оно не является путём на диске. Поле media отправляем JSON-строкой, а байты изображений — отдельными полями.
<?php
declare(strict_types=1);
require __DIR__.'/telegram.php';
$paths = [__DIR__.'/photos/front.jpg', __DIR__.'/photos/detail.jpg'];
$media = [];
$fields = ['chat_id' => requiredEnv('TELEGRAM_CHAT_ID')];
foreach ($paths as $index => $path) {
if (!is_file($path) || !is_readable($path)) {
throw new RuntimeException('Не найден подготовленный файл №'.($index + 1));
}
if ((new finfo(FILEINFO_MIME_TYPE))->file($path) !== 'image/jpeg') {
throw new RuntimeException('В этом примере нужны JPEG-фотографии');
}
$name = 'photo_'.$index;
$item = ['type' => 'photo', 'media' => 'attach://'.$name];
if ($index === 0) {
$item['caption'] = 'Тестовый товар: общий вид и деталь.';
}
$media[] = $item;
$fields[$name] = new CURLFile($path, 'image/jpeg', basename($path));
}
$fields['media'] = json_encode($media, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
$messages = telegram('sendMediaGroup', $fields, true);
if (!array_is_list($messages) || count($messages) !== count($paths)) {
throw new RuntimeException('Неожиданный результат альбома; проверьте чат до повтора');
}
foreach ($messages as $message) {
echo json_encode(['chat_id' => $message['chat']['id'],
'message_id' => $message['message_id'], 'media_group_id' => $message['media_group_id'] ?? null],
JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR), PHP_EOL;
}
php album.php
Один запуск отправляет альбом. Ожидайте две фотографии в одной группе и подпись к первому элементу. Скрипт выводит идентификаторы каждого сообщения. Сохраните их вместе с ID чата и бота; media_group_id полезен для группировки, но не заменяет message_id при дальнейших операциях.
Не задавайте Content-Type: application/json для этого запроса и не собирайте multipart boundary вручную. Простая строка с локальным путём внутри JSON не передаёт файл Telegram.
Подпись, порядок и кнопки
Массив media формируйте в нужном порядке. Короткую общую подпись поместите у первого фото. Для InputMediaPhoto действует ограничение подписи 1024 символа после разбора разметки; большой текст лучше отправить отдельным сообщением.
Начните с обычного текста без parse_mode. Если позже добавите HTML, экранируйте пользовательские значения перед включением в подпись. Не переносите готовую HTML-разметку сайта в Telegram без обработки.
Правила HTML и MarkdownV2 для Telegram
У sendMediaGroup нет параметра reply_markup. Если нужна кнопка «Открыть товар», отправьте отдельное сообщение с клавиатурой после подтверждённого результата альбома. У этих двух операций отдельные результаты: при сбое отправки кнопки не нужно повторять весь альбом.
Отправляем альбом через BotGate SDK
Это альтернативный вариант той же отправки. Установите composer require botgate/sdk; SDK работает на PHP 8.2+. Задайте BOTGATE_API_KEY, BOTGATE_BOT_ID и TELEGRAM_CHAT_ID в окружении. Фотографии остаются в той же папке photos.
<?php
declare(strict_types=1);
require __DIR__.'/vendor/autoload.php';
use BotGate\Client;
use BotGate\Config;
$apiKey = getenv('BOTGATE_API_KEY');
$botId = getenv('BOTGATE_BOT_ID');
if (!is_string($apiKey) || $apiKey === '' || !is_string($botId) || $botId === '') {
throw new RuntimeException('Задайте BOTGATE_API_KEY и BOTGATE_BOT_ID');
}
$bot = Client::fromConfig(new Config(
apiKey: $apiKey,
timeout: 60.0,
maxRetries: 0,
))->bot($botId);
В MultipartField::file передаём открытый поток с содержимым файла. Строка пути в этом аргументе будет содержимым, поэтому здесь нужен fopen. finally закрывает все уже открытые потоки и при успешном ответе, и при исключении.
<?php
declare(strict_types=1);
require __DIR__.'/botgate.php';
use BotGate\Http\MultipartField;
$chatId = getenv('TELEGRAM_CHAT_ID');
if (!is_string($chatId) || $chatId === '') {
throw new RuntimeException('Задайте TELEGRAM_CHAT_ID');
}
$streams = [];
try {
$fields = [MultipartField::field('chat_id', $chatId)];
$media = [];
foreach (['front.jpg', 'detail.jpg'] as $index => $filename) {
$path = __DIR__.'/photos/'.$filename;
if (!is_file($path) || !is_readable($path)
|| (new finfo(FILEINFO_MIME_TYPE))->file($path) !== 'image/jpeg') {
throw new RuntimeException('Проверьте подготовленный JPEG-файл');
}
$stream = fopen($path, 'rb');
if ($stream === false) {
throw new RuntimeException('Не удалось открыть файл');
}
$streams[] = $stream;
$name = 'photo_'.$index;
$media[] = ['type' => 'photo', 'media' => 'attach://'.$name];
$fields[] = MultipartField::file($name, $stream, $filename, 'image/jpeg');
}
$media[0]['caption'] = 'Тестовый товар: общий вид и деталь.';
$fields[] = MultipartField::field('media', json_encode($media,
JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR));
$response = $bot->callMultipart('sendMediaGroup', $fields);
echo json_encode($response->result, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR), PHP_EOL;
} finally {
foreach ($streams as $stream) {
if (is_resource($stream)) {
fclose($stream);
}
}
}
Запустите php album-botgate.php только если хотите выполнить ещё одну тестовую отправку. maxRetries: 0 выбран для явного контроля повторов; эта настройка не отменяет ограничений Telegram и BotGate.
Если альбом не отправился
Ошибка media или attach: сравните имена photo_0 и photo_1 в JSON и файловых полях; проверьте JSON-кодирование media.
Ошибка файла: проверьте реальное содержимое JPEG, доступность пути и допустимые параметры фотографии.
Ошибка доступа: проверьте адрес чата и права того же бота.
Ответ 429: используйте указанную задержку и ограниченное число попыток на одном уровне очереди.
Таймаут или потерянный ответ: сначала проверьте чат и состояние задания. Безусловный повтор может отправить второй альбом.
Не добавляйте кнопку или запись об успешной доставке, пока sendMediaGroup не вернул подтверждённый результат. Для фоновых заданий сохраняйте отдельно состояние отправки альбома и последующего сообщения с кнопкой.
Что проверить на тестовом чате
Порядок фотографий соответствует массиву, подпись не повторяется под каждым фото.
Ответ содержит два message_id, и они сохранены с правильным chat_id.
При отсутствующем втором файле запрос вообще не отправляется.
При исключении SDK открытые потоки закрываются.
Повторное событие приложения не запускает тот же альбом без проверки состояния.