🖼️ Альбомы

Telegram доставляет медиагруппу (альбом) как отдельный апдейт на каждый элемент, поэтому наивный хендлер срабатывает на каждое фото. Middleware альбомов в Raito собирает части и отдаёт вашему хендлеру всю группу сразу.

Он ставится автоматически в setup(), настраивать ничего не нужно.

Получение альбома

Объявите параметр album. Когда сообщение входит в медиагруппу, Raito передаёт полный список; для одиночного элемента параметр не передаётся, поэтому берётся ваше значение по умолчанию:

from aiogram import F, types

router = Router(name="media")


@router.message(F.photo)
async def on_photo(message: types.Message, album: list[types.Message] | None = None):
    if album is None:
        await message.answer("You sent a single photo.")
        return

    await message.answer(f"You sent an album of {len(album)} items.")

Альбом приходит в хендлер, который совпал с первым сообщением группы, и список сохраняет порядок прихода. Работает с любым сгруппированным медиа: фото, видео, документами.

Как работает группировка

Первое сообщение группы открывает короткое окно сбора (delay, по умолчанию около 0,6 с). Каждый следующий апдейт с тем же media_group_id, пришедший в это окно, добавляется в список и подавляется; когда окно закрывается, хендлер первого сообщения получает полный album. Модель middleware описана в Архитектура.

Совет

Группа собирается по таймеру, поэтому очень большой альбом или медленная сеть иногда могут её разбить. Считайте album тем, «что мы успели собрать за момент», и не рассчитывайте на фиксированное количество.