media
Макрос !{media} прикрепляет медиа-ресурсы (фото, видео, аудио, документы и т.д.) к реакциям SendMessage и ShowMenu.
Что умеет макрос:
| Возможность | Описание |
|---|---|
| Одиночный файл | Отправить одно фото, видео, документ |
| Альбом | Отправить до 10 файлов одним сообщением |
| Автоопределение типа | Угадать тип медиа по имени параметра |
| Спойлер | Отправить фото/видео под спойлером |
Где используется:
| Реакция | Назначение |
|---|---|
| SendMessage | Отправить сообщение с медиа (файл прикрепляется к сообщению) |
| ShowMenu | Отправить меню с медиа (файл отображается над кнопками) |
💡 Самый частый сценарий: отправить фото, которое только что прислал пользователь:
!{media|path:${update.message.photo.0}}
Синтаксис
!{media|
параметр1: значение1;
параметр2: значение2;
}
Правила:
- Макрос начинается с
!{media|и заканчивается} - Параметры разделяются символом
;(точка с запятой) - Рекомендуется каждый параметр писать с новой строки
Режимы работы
Макрос работает в трёх режимах. Режим определяется автоматически по наличию параметров.
| Режим | Признак | Что делает |
|---|---|---|
| Path | Есть параметр path | Берёт данные из контекста |
| Альбом | Есть параметры с номерами (id1, url1, ...) | Отправляет несколько файлов |
| Одиночный файл | Ни то, ни другое | Отправляет один файл по ID или URL |
⚠️ Нельзя смешивать режимы в одном вызове.
Общие параметры (для всех режимов)
| Параметр | Тип | Описание |
|---|---|---|
| type | Строка | Тип медиа (photo, video, audio, document, voice, animation, video_note, sticker) |
| spoiler | Boolean | Закрыть медиа спойлером (только для photo, video, animation) |
Режим 1: Path (через путь в контексте)
Самый удобный режим. Вы просто указываете путь к данным, которые уже есть в контексте.
Параметры
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| path | Строка | ✅ Да | Путь к данным в контексте |
| type | Строка | ❌ Нет | Тип медиа (угадывается, если не указан) |
| spoiler | Boolean | ❌ Нет | Закрыть спойлером |
Правила
| Правило | Описание |
|---|---|
| Идентификатор | Объект должен содержать file_id/id или url |
| Приоритет | Сначала ищется file_id, затем url |
| Тип | Поле type желательно. Если его нет — включается автоопределение |
| Спойлер | Поле spoiler необязательно. Параметр spoiler у макроса перекрывает значение из объекта |
| Пропуск | Элементы без валидных данных пропускаются |
Примеры
Одно фото из сообщения пользователя
!{media|path:${update.message.photo.0}}
Альбом из нескольких фото (если в photo массив)
!{media|path:${update.message.photo}}
Файл из результатов формы
!{media|path:${form.fields.attachment}}
Список файлов из локальной переменной
!{media|path:${localVar.files}}
Фото со спойлером
!{media|path:${update.message.photo.0}; spoiler:true}
Режим 2: Одиночный файл (прямое указание)
Используйте этот режим, когда нужно отправить конкретный файл по его file_id или URL.
Через ID файла
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
id |
Строка | ✅ Да | file_id файла (длинная строка от Telegram) |
type |
Строка | ❌ Нет | Тип медиа (угадывается, если не указан) |
spoiler |
Boolean | ❌ Нет | Закрыть спойлером |
Через URL
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
url |
Строка | ✅ Да | HTTP-ссылка на файл |
type |
Строка | ❌ | Нет Тип медиа (угадывается, если не указан) |
spoiler |
Boolean | ❌ | Нет Закрыть спойлером |
Примеры
По file_id
!{media|id:AgACAgIAAxkBAAI...; type:photo}
По URL
!{media|url:https://example.com/photo.jpg; type:photo}
Со спойлером
!{media|id:AgACAgIAAxkBAAI...; type:photo; spoiler:true}
Без указания типа (включится автоопределение)
!{media|id:AgACAgIAAxkBAAI...}
Режим 3: Альбом (несколько файлов)
Для отправки альбома используйте параметры с номерами от 1 до 10.
Параметры
| Параметр | Описание |
|---|---|
| id1 ... id10 | Идентификаторы файлов |
| url1 ... url10 | URL файлов |
| type1 ... type10 | Типы файлов (угадываются, если не указаны) |
| spoiler1 ... spoiler10 | Закрыть соответствующий файл спойлером |
Правила
| Правило | Описание |
|---|---|
| Идентификатор | Каждый файл должен иметь idN или urlN |
| Тип | Если typeN не указан — включается автоопределение |
| Пропуск | Файлы с невалидным типом пропускаются |
| Лимит | Максимум 10 файлов в одном альбоме |
Примеры
Два фото по ID
!{media|id1:AgACAgIAAxkBAAI...; type1:photo; id2:AgACAgIAAxkBAAJ...; type2:photo}
Два фото по URL
!{media|url1:https://example.com/1.jpg; type1:photo; url2:https://example.com/2.jpg; type2:photo}
Первое фото со спойлером, второе без
!{media|id1:${form.photo_id}; type1:photo; spoiler1:true; id2:${form.video_id}; type2:video}
Без указания типов (включится автоопределение)
!{media|id1:${form.photo_id}; id2:${form.video_id}}
Спойлер
Медиа можно отправить закрытым спойлером — размытием, которое раскрывается по тапу пользователя.
Поддержка по типам
| Тип | Поддержка | спойлера |
|---|---|---|
| photo | ✅ | Да |
| video | ✅ | Да |
| animation | ✅ | Да |
audio, document, voice, sticker, video_note ❌ Нет
Как указать спойлер
| Режим | Параметр |
|---|---|
| Path | spoiler:true |
| Одиночный файл | spoiler:true |
| Альбом | spoiler1:true, spoiler2:true, ... |
Особенность режима Path
Если в объекте уже есть поле spoiler/has_spoiler/has_media_spoiler, спойлер будет унаследован. Параметр spoiler у макроса перекрывает значение из объекта.
Доступные типы медиа (справочно)
| Тип | Описание | Спойлер |
|---|---|---|
| photo | Фотография | ✅ |
| video | Видео | ✅ |
| animation | GIF-анимация | ✅ |
| video_note / videonote | Видео-заметка («кружок») | ❌ |
| audio | Аудиофайл (музыка, подкаст) | ❌ |
| voice | Голосовое сообщение | ❌ |
| document | Документ (PDF, ZIP, XLS и др.) | ❌ |
| sticker | Стикер | ❌ |
Частые ошибки и их решение
| Ошибка | Причина | Решение |
|---|---|---|
| Медиа не отправляется | Не указан type, и автоопределение не сработало | Укажите type явно |
| Альбом не формируется | В path передан не массив, а одиночный объект | Убедитесь, что по пути лежит массив объектов |
| Спойлер не работает | Тип медиа не поддерживает спойлер | Спойлер работает только для photo, video, animation |
| Макрос возвращает ошибку | В режиме одиночного файла не удалось определить тип | Укажите type явно |
| Отправляется не то медиа | В массиве по path разные типы, и один из них невалиден | Проверьте структуру данных или используйте альбом с явными типами |
Быстрые ответы (шпаргалка)
Отправить фото из сообщения пользователя
!{media|path:${update.message.photo.0}}
Отправить альбом из нескольких фото
!{media|path:${update.message.photo}}
Отправить документ по URL
!{media|url:https://example.com/file.pdf; type:document}
Отправить видео со спойлером
!{media|id:${video_id}; type:video; spoiler:true}
Отправить два файла по ID
!{media|id1:${id1}; type1:photo; id2:${id2}; type2:video}