Перейти к содержанию
12 минут чтения
Тема: Практика PHP · Фотоальбомы · Multipart

Как отправить несколько фотографий одним альбомом через Telegram-бота

Для примера возьмём карточку товара с двумя фотографиями: общий вид и крупная деталь. Отправим их в тестовый чат одним альбомом, добавим подпись и сохраним идентификаторы сообщений. Разберём прямой запрос к Telegram и такой же запрос через BotGate SDK.

Как описать альбом

В sendMediaGroup передают массив media из 2–10 элементов. У каждой фотографии есть type: photo и media с адресом файла. Подпись задаётся у элемента альбома; в примере она есть только у первого фото. Результат метода — массив сообщений, а не один message_id.

JSON · описание двух фотографий по URL
{
  "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; большую подборку заранее разделите на группы допустимого размера.

Подробная диагностика URL, file_id и загрузки файлов

Готовим локальные фотографии

Основной пример загружает два локальных 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 · telegram.php
<?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 · album.php
<?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;
}
Bash / PowerShell · отправка в тестовый чат
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. Если нужна кнопка «Открыть товар», отправьте отдельное сообщение с клавиатурой после подтверждённого результата альбома. У этих двух операций отдельные результаты: при сбое отправки кнопки не нужно повторять весь альбом.

Как обрабатывать нажатия на inline-кнопки

Отправляем альбом через BotGate SDK

Это альтернативный вариант той же отправки. Установите composer require botgate/sdk; SDK работает на PHP 8.2+. Задайте BOTGATE_API_KEY, BOTGATE_BOT_ID и TELEGRAM_CHAT_ID в окружении. Фотографии остаются в той же папке photos.

PHP · botgate.php
<?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 · album-botgate.php
<?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.

Документация BotGate

Если альбом не отправился

  • Ошибка media или attach: сравните имена photo_0 и photo_1 в JSON и файловых полях; проверьте JSON-кодирование media.

  • Ошибка файла: проверьте реальное содержимое JPEG, доступность пути и допустимые параметры фотографии.

  • Ошибка доступа: проверьте адрес чата и права того же бота.

  • Ответ 429: используйте указанную задержку и ограниченное число попыток на одном уровне очереди.

  • Таймаут или потерянный ответ: сначала проверьте чат и состояние задания. Безусловный повтор может отправить второй альбом.

Не добавляйте кнопку или запись об успешной доставке, пока sendMediaGroup не вернул подтверждённый результат. Для фоновых заданий сохраняйте отдельно состояние отправки альбома и последующего сообщения с кнопкой.

Разбор ограничений и retry_after

Что проверить на тестовом чате

  • Порядок фотографий соответствует массиву, подпись не повторяется под каждым фото.

  • Ответ содержит два message_id, и они сохранены с правильным chat_id.

  • При отсутствующем втором файле запрос вообще не отправляется.

  • При исключении SDK открытые потоки закрываются.

  • Повторное событие приложения не запускает тот же альбом без проверки состояния.

Источники

Telegram: sendMediaGroup

Telegram: InputMediaPhoto

PHP: CURLFile

BotGate SDK