Обработка файлов

Блок «Обработка файлов» позволяет получать информацию о файлах, присланных пользователем, работать с ними внутри сценария бота, а также конвертировать их в другой формат с помощью ffmpeg.

Как добавить блок

В редакторе команды нажмите «+ Добавить блок» → категория Bot → выберите Обработка файлов.

Действие «Получить ссылку на файл»

Действие получает прямую ссылку на скачивание файла через Telegram Bot API и записывает свойства файла в переменную.

Поля

Переменные результата

После выполнения действия доступны три переменные с точечной нотацией:

Если вы задали другое имя переменной (например, my_file), то макросы будут {{my_file.url}}, {{my_file.type}}, {{my_file.size}}.

Режим «Скачать файл»

Когда включена опция Скачать файл:

1. Бот вызывает Telegram API getFile, чтобы получить путь до файла
2. Файл скачивается и сохраняется на сервере платформы в папку bot_files/{id_бота}/
3. В {{file_data.url}} записывается адрес с нашего сервера

Это полезно, когда:

• Нужно, чтобы ссылка была постоянной (ссылки Telegram действуют ограниченное время)
• Файл нужно конвертировать в другой формат
• Файл нужно встроить в сообщение или отправить через внешний сервис

⏱ Ссылка на скачанный файл действует 24 часа, после чего файл автоматически удаляется с сервера.

Конвертация файлов

Опция доступна только при включённом «Скачать файл».

Включите чекбокс «Конвертировать файл», чтобы автоматически конвертировать скачанный файл через ffmpeg.

Поддерживаемые форматы

Для изображений дополнительно доступен виртуальный целевой формат Base64 (Data URL) — он кодирует картинку в строку и записывает её прямо в {{var.url}}. Подробнее — в разделе «Конвертация изображения в Base64» ниже.

Матрица совместимости

Конвертация Видео → Аудио — это извлечение аудиодорожки из видеофайла (например, MP4 → MP3).

Выбор форматов

• Из формата — выберите исходный формат файла (используйте тот формат, в котором приходит файл от Telegram). Список целевых форматов обновляется автоматически в зависимости от выбранного источника.
• В формат — выберите целевой формат. Показывает только форматы, в которые можно конвертировать из исходного.

Прерывать сценарий при ошибках

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

В обоих случаях при ошибке вы получите уведомление от системы.

Дополнительные настройки конвертации

Нажмите ссылку «Дополнительные настройки» для доступа к расширенным параметрам. Все настройки необязательны — если не указаны, ffmpeg использует значения по умолчанию.

Аудио-выход

Видео-выход

Изображение-выход

Хранение конвертированных файлов

• Сконвертированные файлы сохраняются в bot_files/{id_бота}/ с префиксом conv_ в имени.
• Файлы автоматически удаляются через 24 часа (очистка запускается каждый час).
• Исходный скачанный файл удаляется сразу после успешной конвертации.

Пример использования: голосовое → MP3

1. Пользователь присылает голосовое сообщение боту
2. Добавьте блок Обработка файлов → действие Получить ссылку на файл
3. Поле file id: {{FILE_ID}}, переменная: voice_data
4. Включите «Скачать файл» → включите «Конвертировать файл»
5. Выберите: Из формата OGA (Telegram voice) → В формат MP3
6. В следующем блоке Текст вставьте:

   Ваш голосовой в MP3: {{voice_data.url}}
   

Системный макрос {{FILE_ID}}

{{FILE_ID}} — это системная переменная, которая автоматически заполняется при каждом новом сообщении от пользователя:

• Фото → ID наибольшего варианта
• Видео, аудио, документ, голосовое, видео-кружок, анимация (GIF), стикер → file_id этого медиафайла

Если пользователь прислал текстовое сообщение, {{FILE_ID}} не меняется (остаётся последним известным значением).

Действие «Конвертировать файл»

Автономное действие для конвертации уже скачанного файла. Принимает локальный URL файла (например, из действия «Получить ссылку на файл» с включённой опцией «Скачать файл»), конвертирует его через ffmpeg и записывает результат в переменную.

Важно: URL должен указывать на файл, хранящийся на сервере платформы. Внешние ссылки не поддерживаются — при передаче внешней ссылки бот выдаст ошибку.

Поля

Переменные результата

После успешной конвертации доступны переменные (на примере converted_file):

⏱ Ссылка на сконвертированный файл действует 24 часа, после чего файл автоматически удаляется с сервера.

Особое поведение

• Совпадение форматов: если «Из формата» и «В формат» одинаковы — ffmpeg не вызывается, в переменную записывается оригинальный URL.
• Несовместимые форматы: если конвертация между указанными группами форматов невозможна (например, аудио → видео) — будет выдана ошибка.
• Совместимость форматов такая же, как описано в разделе «Конвертация файлов» выше.

Конвертация изображения в Base64 (Data URL)

В качестве цели конвертации для изображений доступен особый формат Base64 (Data URL). Вместо создания файла на сервере платформа кодирует исходное изображение в строку вида data:image/<тип>;base64,... и записывает её в {{var.url}}. Это удобно, когда картинку нужно встроить прямо в HTML — например, в HTML-блок страницы или сообщение с разметкой.

Поддерживаемые исходные форматы: jpg, png, webp, gif.

Лимит размера: 5 МБ. Если файл больше — конвертация завершится ошибкой (поведение зависит от чекбокса «Прерывать сценарий при ошибках»).

Что записывается в переменную результата:

Пример использования в HTML:

<img src="{{converted_file.url}}" alt="preview">

При выборе Base64 раздел «Дополнительные настройки» (ширина/высота/качество/кроп) скрывается — он применим только к ffmpeg-конвертациям. Файл на диск не сохраняется, ссылка живёт ровно столько, сколько живёт значение переменной в состоянии диалога.

Типичная цепочка использования

1. Блок «Обработка файлов» → «Получить ссылку на файл»: file_id = {{FILE_ID}}, переменная voice_data, включить «Скачать файл» (конвертацию не включать)
2. Блок «Обработка файлов» → «Конвертировать файл»: ссылка {{voice_data.url}}, переменная mp3_data, Из формата OGA (Telegram voice) → В формат MP3
3. В следующем блоке: Ваш MP3: {{mp3_data.url}}

Это полезно, когда нужно применить несколько последовательных конвертаций к одному файлу или использовать URL, полученный из другого источника (например, из переменной базы данных).