Почему один альбом приходит несколькими событиями
У каждого элемента есть собственные message_id и update_id, а сообщения одного альбома объединяет строковый media_group_id. Входящий webhook не содержит готовый массив всех элементов с признаком «это последняя фотография». Эти поля описаны в структуре Message.
Массив message.photo — это варианты размера одной фотографии, а не фотографии альбома. Из него выбирайте один подходящий PhotoSize для хранения или скачивания. Если сохранить каждый элемент photo как самостоятельное вложение, одна фотография превратится в несколько дублей.
Ниже используем PHP 8.3+, PDO SQLite и уже настроенный приём обновлений. Пример показывает накопление метаданных в БД. Скачивание файлов и доставка менеджеру выполняются отдельными заданиями после сохранения; webhook не ждёт весь альбом.
Отправку исходящего альбома разбирает другое руководство. Здесь задача обратная: надёжно принять несколько независимых событий от пользователя.
Задаём ключи и привязываем альбом к заявке
Составной ключ альбома: bot_id, chat_id и media_group_id. Не приводите media_group_id к целому числу. Для элемента нужен уникальный ключ (bot_id, chat_id, message_id), а для приёма update — (bot_id, update_id). Эти ключи защищают разные уровни обработки.
При первом элементе определите активную заявку пользователя и сохраните request_id в строке альбома. Последующие элементы ищут уже созданную группу и наследуют её request_id. Нельзя каждый раз брать «текущую заявку»: пользователь мог успеть открыть другую анкету между доставками.
CREATE TABLE incoming_albums ( bot_id TEXT NOT NULL, chat_id INTEGER NOT NULL, media_group_id TEXT NOT NULL, request_id INTEGER NOT NULL, state TEXT NOT NULL DEFAULT 'collecting', revision INTEGER NOT NULL DEFAULT 0, ready_at INTEGER NOT NULL, PRIMARY KEY (bot_id, chat_id, media_group_id) ); CREATE TABLE album_items ( bot_id TEXT NOT NULL, chat_id INTEGER NOT NULL, message_id INTEGER NOT NULL, media_group_id TEXT NOT NULL, file_id TEXT NOT NULL, caption TEXT NOT NULL, PRIMARY KEY (bot_id, chat_id, message_id) );
В рабочей схеме дополнительно храните отправителя, время первого элемента, срок ожидания подтверждения и связь с вашей таблицей заявок. Проверяйте, что заявка принадлежит этому пользователю и принимает вложения. В примере используется личный чат; сценарий общей группы потребует учёта отправителя и выбранного обращения.
Текстовая подпись может прийти с одним из элементов, и полагаться на порядок доставки нельзя. Сохраните caption возле исходного message_id. Для карточки заявки используйте подписи в порядке сообщений, а не «подпись первого пришедшего update».
Добавляем фотографию без повторного вложения
Функция ниже принимает уже проверенные bot_id, chat_id, message_id, media_group_id и request_id. FileId выбирается из message.photo по нужному размеру; caption может быть пустым. Параметр now — Unix timestamp времени приёма. Для SQLite захват записи выполняется BEGIN IMMEDIATE; вызывать функцию внутри другой транзакции не нужно.
<?php
declare(strict_types=1);
function collectPhoto(
PDO $db, string $botId, int $chatId, string $groupId,
int $requestId, int $messageId, string $fileId, string $caption, int $now,
): bool {
$db->exec('BEGIN IMMEDIATE');
try {
$q = $db->prepare('INSERT INTO incoming_albums
(bot_id, chat_id, media_group_id, request_id, ready_at)
VALUES (?, ?, ?, ?, ?) ON CONFLICT DO NOTHING');
$q->execute([$botId, $chatId, $groupId, $requestId, $now + 2]);
$q = $db->prepare('SELECT state FROM incoming_albums
WHERE bot_id = ? AND chat_id = ? AND media_group_id = ?');
$q->execute([$botId, $chatId, $groupId]);
if ($q->fetchColumn() !== 'collecting') {
throw new LogicException('Альбом уже закрыт: обработайте поздний элемент отдельно');
}
$q = $db->prepare('INSERT INTO album_items
(bot_id, chat_id, message_id, media_group_id, file_id, caption)
VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT DO NOTHING');
$q->execute([$botId, $chatId, $messageId, $groupId, $fileId, $caption]);
$added = $q->rowCount() === 1;
if ($added) {
$q = $db->prepare('UPDATE incoming_albums
SET revision = revision + 1, ready_at = ?
WHERE bot_id = ? AND chat_id = ? AND media_group_id = ?');
$q->execute([$now + 2, $botId, $chatId, $groupId]);
}
$db->exec('COMMIT');
return $added;
} catch (Throwable $error) {
$db->exec('ROLLBACK');
throw $error;
}
}
Подключение PDO должно использовать ERRMODE_EXCEPTION. При повторе одного message_id функция возвращает false и не продлевает ожидание. Request_id существующего альбома не переписывается. Для MySQL/PostgreSQL перенесите алгоритм на их синтаксис и блокировку строки: буквальная копия SQLite-команд туда не подходит.
Приёмник сначала надёжно сохраняет update, затем подтверждает доставку. Обработчик может повторить локальную обработку после временной ошибки БД. Для уже закрытого альбома LogicException — сигнал отдельной ветки поздних сообщений, а не причина бесконечно повторять webhook. Сохранённое исходное событие позволяет разобрать ситуацию без потери фотографии.
Ожидаем паузу и подтверждаем состав альбома
После каждого нового элемента ready_at сдвигается на две секунды. Worker выбирает collecting с ready_at <= now(). Это лишь удобная задержка для интерфейса: Telegram не обещает, что через две секунды будут доставлены все фотографии. Значение выбирайте по нагрузке, а не выдавайте его за признак полноты.
Для оценки ремонта лучше показывать предварительный список после паузы: «Получено 4 фото. Всё добавлено?» с кнопкой «Готово». Новая фотография увеличивает revision и обновляет предварительный состав. В callback подтверждения передайте ссылку на альбом и revision, проверьте владельца заявки и действующий шаг.
Закрытие выполняйте короткой транзакцией: заново загрузите альбом, проверьте revision и отсутствие новых элементов, затем измените collecting на confirmed и создайте одно задание обработки с уникальным ключом альбома. Если revision изменилась, покажите обновлённый состав и попросите подтвердить его. Сетевые операции выполняются после commit.
Если после подтверждения пришёл неизвестный message_id той же группы, сохраните его как позднее вложение, свяжите с прежним request_id и уведомите пользователя или оператора. Не создавайте новую заявку автоматически и не добавляйте файл молча к уже отправленному менеджеру набору. Повтор ранее принятого message_id отбрасывайте до этой ветки по уникальному ключу.
Не оставляйте collecting навсегда: например, через 30 минут без подтверждения переведите группу в expired, сохранив принятые вложения на установленный срок. Пользователь должен видеть возможность вернуться к черновику или начать заново. Для сценария без кнопки «Готово» заранее определите такую же политику поздних элементов.
Сохраняем порядок и скачиваем нужные файлы
Читать элементы нужно с ORDER BY message_id, а не по времени получения webhook. Это даёт порядок сообщений в исходном чате. Для нескольких групп одной заявки дополнительно сохраните порядок самих групп. Уникальный media_group_id не заменяет порядок элементов.
Для отправки и getFile нужен file_id; file_unique_id пригоден для сопоставления, но не для скачивания. File_id относится к тому боту, который получил файл. Не переносите его в запросы другого бота. Подробный путь загрузки разобран в статье о получении и сохранении файлов.
Worker скачивает файлы по одному, проверяет ограничения размера и сохраняет результат под собственным безопасным именем. Исходное имя и подпись не используйте как путь. Ошибка одной загрузки должна оставаться видимой: статус заявки «все фото сохранены» ставится только после подтверждения нужных файлов.
Альбом может содержать неподдерживаемые вашим сценарием типы. Если принимаете только фото, обработайте video/document явно: сообщите, что этот элемент не вошёл в набор. Одиночное фото без media_group_id принимайте отдельной веткой вложений, не объединяя все такие сообщения под пустым ключом.
Проверяем задержки и повторную доставку
Отправьте три фотографии одним альбомом: получится одна группа и три вложения, а не по записи на каждый размер photo.
Обработайте события в обратном порядке: итоговый список отсортирован по message_id.
Повторите update и message_id: число вложений и revision не меняются.
Перезапустите worker после первого фото: накопленные данные остаются в БД.
Пришлите последнюю фотографию после паузы и после подтверждения: обе ситуации проходят предусмотренные ветки.
Откройте другую заявку до прихода задержанного элемента: прежний альбом остаётся у первоначальной заявки.
Через BotGate входящие части альбома также обрабатывает ваше приложение. Сборщик, таймер и подтверждение пользователя не заменяются транспортом webhook. Проверяйте подпись по документации сервиса, а неизвестный результат исходящей отправки менеджеру разбирайте отдельно от повторной доставки входящих фотографий.