media

Макрос !{media} прикрепляет медиа-ресурсы (фото, видео, аудио, документы и т.д.) к реакциям SendMessage и ShowMenu.

Что умеет макрос:

Где используется:

💡 Самый частый сценарий: отправить фото, которое только что прислал пользователь:

• !{media|path:${update.message.photo.0}}

Синтаксис

   !{media|
   параметр1: значение1;
   параметр2: значение2;
   }

Правила:

• Макрос начинается с !{media| и заканчивается }
• Параметры разделяются символом ; (точка с запятой)
• Рекомендуется каждый параметр писать с новой строки

Режимы работы

Макрос работает в трёх режимах. Режим определяется автоматически по наличию параметров.

⚠️ Нельзя смешивать режимы в одном вызове.

Общие параметры

⚠️ В режиме Path параметр type не действует — тип берётся из самого объекта или угадывается по значению path. Параметр spoiler в режиме Path действует только когда по пути лежит один объект, а не список.

Режим 1: Path (через путь в контексте)

Самый удобный режим. Вы просто указываете путь к данным, которые уже есть в контексте.

Параметры

⚠️ Параметр type в этом режиме не действует. Тип берётся из самого объекта, а если его там нет — угадывается по значению path (см. «Автоопределение типа»).

Что можно передать в path

Все три варианта равнозначны — макрос сам определяет, что ему передали.

Формат данных

Один объект

{
  "file_id": "AgACAgIAAxk...",
  "file_type": "photo",
  "spoiler": true
}

Список объектов (альбом)

[
  {"file_id": "AgACAgIAAxk1...", "type": "photo", "spoiler": true},
  {"file_id": "AgACAgIAAxk2...", "type": "video"},
  {"url": "https://example.com/file.jpg", "type": "photo"}
]

Правила

💡 Файлы, которые пользователь прислал в форму, приходят с полем file_type — тип для них определяется сам, указывать ничего не нужно.

Примеры

Одно фото из сообщения пользователя

!{media|path:${update.message.photo.0}}

То же самое, путём без скобок

!{media|path:update.message.photo.0}

Альбом из нескольких фото (если в photo массив)

!{media|path:${update.message.photo}}

Файл, который пользователь загрузил в форму

!{media|path:${form.fields.screenshot.0}}

Список файлов из локальной переменной

!{media|path:${var.local.files}}

Фото со спойлером

!{media|path:${update.message.photo.0}; spoiler:true}

⚠️ Спойлер параметром можно поставить только когда по пути лежит один объект. Если там список, спойлер берётся из самих объектов, а параметр spoiler игнорируется.

Режим 2: Одиночный файл (прямое указание)

Используйте этот режим, когда нужно отправить конкретный файл по его file_id или URL.

Через ID файла

Через URL

Примеры

По 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.

Параметры

Правила

Примеры

Два фото по 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}}

Автоопределение типа

Если тип не указан, макрос пытается угадать его по значению параметра — path, id, url (и idN, urlN в альбоме). Смотрится текст как он написан в настройке, до подстановки переменных, поэтому имя типа достаточно упомянуть в пути.

Примеры

Правила

⚠️ Обратная сторона: имя типа ищется в любом месте строки. Путь var.local.myphotos даст тип photo, даже если по нему лежит документ. В таких случаях указывайте тип явно или храните его в самом объекте.

Когда угадывание не сработает: если в записи нет имени типа — например ${var.local.file} или ${form.result.0}.

Спойлер

Медиа можно отправить закрытым спойлером — размытием, которое раскрывается по тапу пользователя.

Поддержка по типам

Для типов без поддержки параметр просто игнорируется.

Как указать спойлер

Допустимые значения

Регистр не имеет значения.

Особенность режима Path

Если в объекте уже есть поле spoiler, has_spoiler или has_media_spoiler, спойлер будет унаследован — медиа, изначально присланное под спойлером, останется под спойлером.

Параметр spoiler у макроса перекрывает значение из объекта, только когда по пути лежит один объект. Для списка объектов параметр игнорируется, и спойлер каждого файла берётся из его собственных полей.

Доступные типы медиа (справочно)

Частые ошибки и их решение

Быстрые ответы (шпаргалка)

Отправить фото из сообщения пользователя

!{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}