Botconsole
RU EN
Вход Начать бесплатно
Продукт Temlates Блог Партнёрам Веб-виджет Как это работает Тарифы Вход Начать бесплатно
RU EN

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

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

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

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

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

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

Поля

Поле По умолчанию Описание
Укажите file id {{FILE_ID}} ID файла, присланного пользователем. По умолчанию используется системный макрос {{FILE_ID}}, в который автоматически записывается file_id последнего полученного от пользователя файла.
Записать в переменную file_data Название переменной, в которую будут записаны свойства файла.
Скачать файл выключено Если включено — файл скачивается на сервер платформы, и в переменную записывается локальный URL. Необходимо для конвертации файла.

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

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

Макрос Значение
{{file_data.url}} Прямая ссылка на скачивание файла
{{file_data.type}} Тип файла: photo, video, audio или document
{{file_data.size}} Размер файла в байтах

Если вы задали другое имя переменной (например, 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.

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

Группа Форматы
Аудио OGA (Telegram voice), MP3, M4A, WAV, AAC
Видео MP4, MOV, AVI, WebM
Изображение JPEG, PNG, WebP, GIF

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

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

Из \ В Аудио Видео Изображение
Аудио ✅ ❌ ❌
Видео ✅ (извлечь аудиодорожку) ✅ ❌
Изображение ❌ ❌ ✅

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

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

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

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

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

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

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

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

Аудио-выход

Параметр Описание
Битрейт Скорость потока аудио: 64k, 96k, 128k (по умолчанию), 192k, 256k, 320k
Частота дискретизации 8000, 16000, 22050, 44100, 48000 Гц. По умолчанию — исходная.
Каналы Исходные / Моно / Стерео

Видео-выход

Параметр Описание
Максимальное разрешение Исходное / 640×360 / 1280×720 / 1920×1080
FPS Исходный / 24 / 30 / 60 кадров в секунду
Видео-кодек Авто / H.264 (libx264) / H.265 (libx265) / VP9 (libvpx-vp9)
Качество (CRF) От 0 (максимальное качество, большой файл) до 51 (минимальное). По умолчанию 23.

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

Параметр Описание
Ширина (px) Целевая ширина. Высота масштабируется пропорционально, если не указана.
Высота (px) Целевая высота. Ширина масштабируется пропорционально, если не указана.
Качество сжатия (1–100) Для JPEG и WebP: 100 = максимальное. Для PNG игнорируется.
Обрезка (WxH:X:Y) Обрезать изображение. Формат: 640x480:0:0 — размер 640×480, начальная координата (0, 0).

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

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

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

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

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

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

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

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

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

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

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

Поля

Поле По умолчанию Описание
Ссылка на файл — Локальный URL файла или переменная с URL. Должен содержать адрес сервера платформы. Например: {{file_data.url}}
Записать результат в переменную converted_file Название переменной, куда будут записаны свойства сконвертированного файла.
Прерывать сценарий при ошибках выключено Если включено — при ошибке конвертации бот остановится и вы получите уведомление. Если выключено — бот продолжит сценарий без изменения переменной результата.
Из формата / В формат mp3 → oga Направление конвертации. Используйте те же форматы, что и в действии «Получить ссылку на файл».
Дополнительные настройки — Битрейт, частота, каналы, кодек и другие параметры ffmpeg.

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

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

Макрос Значение
{{converted_file.url}} Ссылка на сконвертированный файл
{{converted_file.type}} Тип файла: photo, video, audio, document
{{converted_file.size}} Размер файла в байтах
{{converted_file.ext}} Расширение файла (mp3, oga, jpg...)
{{converted_file.fileName}} Имя файла с расширением

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

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

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

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

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

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

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

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

Макрос Значение
{{converted_file.url}} Полная строка data:image/<mime>;base64,...
{{converted_file.type}} photo
{{converted_file.ext}} base64
{{converted_file.size}} Размер исходного файла в байтах
{{converted_file.fileName}} Имя исходного файла

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

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, полученный из другого источника (например, из переменной базы данных).

Действие «Создать текстовый документ»

Создаёт файл с текстом или кодом — например, отчёт в CSV, лог-файл, JSON-выгрузку или файл субтитров — и записывает ссылку на него в переменную. Файл собирается прямо из шаблона с переменными, без конвертации.

Поля

Поле По умолчанию Описание
Содержание файла — Текст файла. Поддерживает переменные {{...}} — можно вставить туда результат другого блока, данные пользователя и т.д.
Формат файла TXT Выбор из TXT, CSV, SRT, JSON, JS, Markdown, XML, YAML, HTML, CSS, SQL, LOG. Определяет расширение итогового файла.
Название файла — Имя файла без расширения, поддерживает переменные. Если не указано — генерируется автоматически.
Кодировка UTF-8 Также доступны UTF-8 с BOM, Windows-1251, KOI8-R — на случай, если файл предназначен для программы, которая не понимает UTF-8.
Записать результат в переменную document Название переменной для свойств созданного файла.

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

Макрос Значение
{{document.url}} Ссылка на файл
{{document.size}} Размер файла в байтах
{{document.format}} Формат файла
{{document.fileName}} Имя файла с расширением

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

В редакторе есть кнопка «Тест» — она сразу создаёт файл по текущим настройкам и показывает ссылку, не дожидаясь запуска бота.

Действие «Получить аудио из видео»

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

Поля

Поле По умолчанию Описание
Ссылка на видео — Локальная ссылка на видеофайл. Внешние ссылки не поддерживаются.
Начало — Необязательно. С какой секунды начать вырезку — можно указать секунды (90) или время в формате 00:01:30.
Конец / Длительность — Необязательно. Момент окончания вырезки либо длительность фрагмента — переключается рядом чекбоксом.
Формат аудио MP3 MP3, WAV, OGG, M4A, AAC, Opus, FLAC.
Битрейт 192k Качество (размер) итогового аудиофайла.
Исполнитель — Записывается в тег «Артист» аудиофайла. Поддерживает переменные.
Название трека — Записывается в тег «Название» аудиофайла. Поддерживает переменные.
Записать результат в переменную audio Название переменной для свойств результата.

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

Макрос Значение
{{audio.url}} Ссылка на аудиофайл
{{audio.size}} Размер файла в байтах
{{audio.format}} Формат аудио
{{audio.artist}} Исполнитель (если указан)
{{audio.title}} Название трека (если указано)

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

Если поля «Начало» и «Конец» оставить пустыми — извлекается вся аудиодорожка целиком.

Действие «Объединить аудио»

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

Поля

Поле По умолчанию Описание
Ссылки на аудиофайлы 2 пустых поля Локальные ссылки на аудиофайлы в порядке склейки. Кнопка «+ Добавить аудио» добавляет ещё поле — максимум 10 файлов.
Формат результата MP3 MP3, WAV, OGG, M4A, AAC, Opus, FLAC.
Нормализовать громкость выключено Приводит все файлы к одному уровню громкости, чтобы при склейке не было резких перепадов звука.
Тишина между файлами (сек) 0 Добавляет паузу между соседними файлами.
Дополнительные настройки — Битрейт, частота дискретизации, каналы (моно/стерео).
Записать результат в переменную merged_audio Название переменной для свойств результата.

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

Макрос Значение
{{merged_audio.url}} Ссылка на итоговый аудиофайл
{{merged_audio.size}} Размер файла в байтах
{{merged_audio.format}} Формат аудио

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

Действие «Замена/наложение аудио в видео»

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

Поля

Поле По умолчанию Описание
Режим Заменить Переключатель «Заменить» / «Наложить».
Ссылка на видео — Локальная ссылка на видео.
Ссылка на аудио — Локальная ссылка на аудиофайл.
Зациклить аудио включено Если аудио короче видео — оно повторяется до конца видео. Если длиннее — обрезается по длине видео. Итоговый ролик всегда останавливается по самой короткой дорожке.
Громкость наложенного аудио (%) 10 Только в режиме «Наложить» — насколько громко звучит новая дорожка поверх исходной.
Смещение аудио (сек) 0 Задержка перед стартом нового аудио относительно начала видео.
Настройки видео как в исходном файле Разрешение и качество; если не заданы — видео сохраняет исходное качество без перекодирования.
Записать результат в переменную video Название переменной для свойств результата.

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

Макрос Значение
{{video.url}} Ссылка на итоговое видео
{{video.size}} Размер файла в байтах
{{video.format}} Формат видео

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

Действие «Изменить скорость аудио»

Ускоряет или замедляет локальный аудиофайл.

Поля

Поле По умолчанию Описание
Ссылка на аудио — Локальная ссылка на аудиофайл.
Скорость 1.0 Множитель скорости от 0.25 (в 4 раза медленнее) до 4.0 (в 4 раза быстрее).
Сохранить тон включено Если включено — голос звучит с той же высотой тона, только быстрее/медленнее. Если выключено — тон меняется вместе со скоростью (классический эффект «бурундук» на ускорении или «замедленного голоса» на замедлении).
Записать результат в переменную speed_audio

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

Макрос Значение
{{speed_audio.url}} Ссылка на обработанный файл
{{speed_audio.size}} Размер файла в байтах
{{speed_audio.format}} Формат файла

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

Действие «Обрезать аудио/видео»

Вырезает нужный отрезок из локального аудио- или видеофайла, не меняя формат файла.

Поля

Поле По умолчанию Описание
Ссылка на файл — Локальная ссылка на аудио или видео.
Начало — Необязательно. Секунды (90) или время 00:01:30.
Конец / Длительность — Необязательно. Момент окончания либо длительность отрезка — переключается чекбоксом рядом.
Точная обрезка (перекодирование) выключено По умолчанию обрезка быстрая, но для видео точка начала может слегка сдвинуться до ближайшего опорного кадра. Включите для покадрово точной обрезки — медленнее, файл перекодируется заново.
Записать результат в переменную trimmed_media

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

Макрос Значение
{{trimmed_media.url}} Ссылка на обрезанный файл
{{trimmed_media.size}} Размер файла в байтах
{{trimmed_media.format}} Формат файла

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

Действие «Громкость и динамика аудио»

Четыре независимых настройки громкости, которые можно комбинировать в одном действии.

Поля

Поле По умолчанию Описание
Ссылка на аудио —
Установить громкость выключено Множитель (1.0 = без изменений, 2.0 = вдвое громче) или значение в дБ (6dB).
Динамическая компрессия выключено Сглаживает резкие перепады громкости в записи — полезно для голосовых сообщений с неровной громкостью.
Нормализация громкости выключено Приводит запись к стандартной целевой громкости (LUFS, по умолчанию −23 — вещательный стандарт).
Плавное появление/затухание выключено Отдельные поля длительности появления и затухания звука в секундах.

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

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

Макрос Значение
{{audio_volume.url}} Ссылка на обработанный файл
{{audio_volume.size}} Размер файла в байтах
{{audio_volume.format}} Формат файла

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

Действие «Эффекты и обработка аудио»

До восьми звуковых эффектов, каждый включается своим чекбоксом и применяется в фиксированном порядке: шумоподавление → бас-буст → хорус → фленджер → фейзер → эхо → реверберация → эффект телефона.

Доступные эффекты

Эффект Настройки Описание
Шумоподавление — Убирает фоновый шум записи.
Бас-буст Сила, 0–100% Усиливает низкие частоты.
Хорус Сила, 0–100% Эффект «многоголосия», как будто играет несколько инструментов/голосов одновременно.
Фленджер Сила, 0–100% Металлический «свистящий» эффект модуляции.
Фейзер Сила, 0–100% Мягкий «плывущий» эффект модуляции фазы.
Эхо Входное/выходное усиление, задержка (мс), затухание Классическое эхо с полным набором параметров.
Реверберация — Имитация звучания в помещении/зале.
Эффект телефона — Обрезает частоты до узкой полосы, как в телефонной трубке.

Включите хотя бы один эффект — можно комбинировать сколько угодно.

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

Макрос Значение
{{processed_audio.url}} Ссылка на обработанный файл
{{processed_audio.size}} Размер файла в байтах
{{processed_audio.format}} Формат файла

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

Действие «Анализ и метаданные аудио»

Читает техническую информацию и уже существующие теги локального аудиофайла — сам файл не изменяется, новый файл не создаётся.

Поля

Поле По умолчанию Описание
Ссылка на аудио —
Записать результат в переменную audio_info

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

Макрос Значение
{{audio_info.duration}} Длительность в секундах
{{audio_info.bitrate}} Битрейт
{{audio_info.sample_rate}} Частота дискретизации (Hz)
{{audio_info.channels}} Число каналов
{{audio_info.codec}} Кодек
{{audio_info.size}} Размер файла в байтах
{{audio_info.format}} Формат
{{audio_info.title}} {{audio_info.artist}} {{audio_info.album}} {{audio_info.genre}} {{audio_info.track}} {{audio_info.date}} Существующие теги (пусто, если тег отсутствует)

Действие «Добавить обложку в аудио»

Встраивает изображение как обложку в локальный аудиофайл — поддерживаются MP3, M4A, OGG, FLAC.

Поля

Поле По умолчанию Описание
Ссылка на аудио —
Ссылка на изображение — JPG или PNG.
Записать результат в переменную audio_with_cover

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

Макрос Значение
{{audio_with_cover.url}} Ссылка на файл с обложкой
{{audio_with_cover.size}} Размер файла в байтах
{{audio_with_cover.format}} Формат файла

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

Действие «Изменить метаданные аудио»

Редактирует теги (название, исполнитель, альбом и т.д.) локального аудиофайла.

Поля

Поле По умолчанию Описание
Ссылка на аудио —
Название / Исполнитель / Альбом / Жанр / Номер трека / Дата — Каждое поле поддерживает переменные. Рядом с каждым полем — чекбокс «Очистить»: если отметить его, тег удаляется независимо от того, что написано в поле. Если поле оставлено пустым и чекбокс не отмечен — существующий тег не трогается.
Записать результат в переменную audio_meta

Заполните хотя бы одно поле или отметьте хотя бы один чекбокс «Очистить».

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

Макрос Значение
{{audio_meta.url}} Ссылка на обновлённый файл
{{audio_meta.size}} Размер файла в байтах
{{audio_meta.format}} Формат файла

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

Статус выполнения и обработка ошибок

Каждое действие блока «Обработка файлов» — все 15, включая новые аудио-действия, — помимо своего результата всегда записывает ещё две служебные переменные:

Макрос Значение
{{prefix.status}} success, если действие выполнилось успешно, или error, если произошла ошибка
{{prefix.error_message}} Текст ошибки (пусто, если всё прошло успешно)

Где prefix — то же имя переменной, что вы указали в поле «Записать результат в переменную» (или «Префикс результата» для HTML → PDF/PNG).

Это удобно использовать в паре с блоком «Условие», добавленным сразу после блока «Обработка файлов»: проверьте {{prefix.status}} == error, и если условие выполняется — покажите пользователю сообщение об ошибке, попробуйте другой путь сценария или отправьте уведомление вам.

Пример: после действия «Получить аудио из видео» с переменной audio добавьте блок «Условие» с проверкой {{audio.status}} равно error → в этой ветке отправьте текст «Не удалось обработать видео, попробуйте другой файл», а в остальных случаях продолжайте сценарий как обычно.