File Processing

The "File Processing" block allows you to retrieve information about files sent by the user, work with them within the bot scenario, and convert them to a different format using ffmpeg.

How to add the block

In the command editor, click "+ Add block" → Bot category → select File Processing.

"Get file link" action

This action retrieves a direct download link for the file via the Telegram Bot API and saves the file's properties into a variable.

Fields

Result variables

After the action executes, three variables using dot notation become available:

If you specified a different variable name (e.g., my_file), the macros will be my_file.url, my_file.type, and my_file.size. ---

"Download File" Mode

When the Download File option is enabled:

1. The bot calls the Telegram API getFile method to retrieve the file path.
2. The file is downloaded and saved to the platform server in the bot_files/{bot_id}/ folder.
3. The address from our server is stored in file_data.url.

This is useful when:

• You need a permanent link (Telegram links are temporary)
• You need to convert the file to a different format
• You need to embed the file in a message or send it via an external service

⏱ The link to the downloaded file is valid for 24 hours, after which the file is automatically deleted from the server.

File Conversion

This option is available only when "Download file" is enabled.

Check the "Convert file" box to automatically convert the downloaded file using ffmpeg.

Supported Formats

For images, a virtual target format—Base64 (Data URL)—is also available; it encodes the image into a string and writes it directly to var.url. See the "Converting an Image to Base64" section below for details.

Compatibility Matrix

Video → Audio conversion involves extracting the audio track from the video file (e.g., MP4 → MP3).

Selecting Formats

• From format — select the source file format (use the format in which the file is received from Telegram). The list of target formats updates automatically based on the selected source.
• To format — select the target format. Only formats compatible with the source format are displayed. ### Stop scenario on error

If this option is enabled, the bot will stop at the current step if a conversion error occurs, and you will receive a notification via Telegram. It is disabled by default: if an error occurs, the bot continues the scenario using the link to the original (unconverted) file.

In either case, you will receive a system notification if an error occurs.

Advanced conversion settings

Click the "Advanced settings" link to access extended parameters. All settings are optional; if none are specified, ffmpeg uses default values.

Audio Output

Video Output

Image Output

Storage of converted files

• Converted files are saved in bot_files/{bot_id}/ with the prefix conv_ in the filename.
• Files are automatically deleted after 24 hours (cleanup runs every hour).
• The original downloaded file is deleted immediately after successful conversion.

Usage example: Voice message → MP3

1. The user sends a voice message to the bot.
2. Add a File Processing block → Get file link action.
3. File ID field: FILE_ID, variable: voice_data.
4. Enable "Download file" → enable "Convert file".
5. Select: From format OGA (Telegram voice) → To format MP3.
6. In the next Text block, insert:

Your voice message as MP3: {{voice_data.url}}

System Macro FILE_ID

FILE_ID is a system variable that is automatically populated with every new message from the user:

• Photo → ID of the largest version
• Video, audio, document, voice message, video note, animation (GIF), sticker → file_id of the media file

If the user sends a text message, FILE_ID does not change (it retains the last known value).

"Convert File" Action

A standalone action for converting a file that has already been downloaded. It accepts a local file URL (e.g., from the "Get File Link" action with the "Download file" option enabled), converts it using ffmpeg, and saves the result to a variable.

Important: The URL must point to a file stored on the platform's server. External links are not supported; the bot will return an error if an external link is provided.

Fields

After successful conversion, the following variables are available (using converted_file as an example):

⏱ The link to the converted file is valid for 24 hours, after which the file is automatically deleted from the server.

Special Behavior

• Matching formats: If the "From format" and "To format" are identical, ffmpeg is not called, and the original URL is saved to the variable.
• Incompatible formats: If conversion between the specified format groups is impossible (e.g., audio → video), an error will occur.
• Format compatibility is the same as described in the "File Conversion" section above.

Converting Images to Base64 (Data URL)

A special Base64 (Data URL) format is available as a conversion target for images. Instead of creating a file on the server, the platform encodes the source image into a string like data:image/;base64,... and saves it to var.url. This is useful when you need to embed an image directly into HTML—for example, in an HTML page block or a message with markup.

Supported source formats: jpg, png, webp, gif.

Size limit: 5 MB. If the file exceeds this size, the conversion will fail (behavior depends on the "Abort scenario on error" checkbox).

Data saved to the result variable:

Example of HTML usage:

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

When Base64 is selected, the "Additional settings" section (width/height/quality/crop) is hidden, as it applies only to ffmpeg conversions. The file is not saved to disk; the link remains valid only as long as the variable exists within the dialog state.

Typical workflow

1. "File Processing" block → "Get file link": file_id = FILE_ID, variable voice_data, enable "Download file" (do not enable conversion).
2. "File Processing" block → "Convert file": link voice_data.url, variable mp3_data, convert from OGA (Telegram voice) to MP3.
3. In the next block: Your MP3: mp3_data.url

This is useful when you need to perform multiple sequential conversions on a single file or use a URL obtained from another source (e.g., a database variable).

"Create Text Document" Action

Creates a text or code file — for example, a CSV report, a log file, a JSON export, or a subtitle file — and saves a link to it in a variable. The file is assembled directly from a template with variables, with no conversion step involved.

Fields

Result variables

⏱ The file link is valid for 24 hours, after which the file is automatically deleted from the server.

The editor includes a "Test" button that creates the file immediately with the current settings and shows you the link, without having to run the bot.

"Extract Audio From Video" Action

Extracts the audio track from a local video file (e.g., obtained via the "Get file link" action with "Download file" enabled) and saves it as a separate audio file. You can trim just the part you need instead of the whole track.

Fields

Result variables

⏱ The file link is valid for 24 hours, after which the file is automatically deleted from the server.

If both "Start" and "End" are left empty, the entire audio track is extracted.

"Merge Audio" Action

Joins several local audio files, one after another, into a single file — for example, to assemble a playlist or a sequence of voice replies.

Fields

Result variables

⏱ The file link is valid for 24 hours, after which the file is automatically deleted from the server.

"Replace/Overlay Audio in Video" Action

Changes a local video's audio track to a different audio file — either fully replacing it or overlaying the new audio on top of the original sound.

Fields

Result variables

⏱ The file link is valid for 24 hours, after which the file is automatically deleted from the server.

"Change Audio Speed" Action

Speeds up or slows down a local audio file.

Fields

Result variables

⏱ The file link is valid for 24 hours, after which the file is automatically deleted from the server.

"Trim Audio/Video" Action

Cuts out the part you need from a local audio or video file, without changing the file's format.

Fields

Result variables

⏱ The file link is valid for 24 hours, after which the file is automatically deleted from the server.

"Audio Volume and Dynamics" Action

Four independent volume-related settings that can be combined within a single action.

Fields

Enable at least one of the four settings — they're applied together, in the order listed.

Result variables

⏱ The file link is valid for 24 hours, after which the file is automatically deleted from the server.

"Audio Effects and Processing" Action

Up to eight audio effects, each toggled by its own checkbox and applied in a fixed order: noise reduction → bass boost → chorus → flanger → phaser → echo → reverb → telephone effect.

Available effects

Enable at least one effect — you can combine as many as you like.

Result variables

⏱ The file link is valid for 24 hours, after which the file is automatically deleted from the server.

"Audio Analysis and Metadata" Action

Reads technical information and existing tags from a local audio file — the file itself is not modified, and no new file is created.

Fields

Result variables

"Add Cover Art to Audio" Action

Embeds an image as cover art into a local audio file — MP3, M4A, OGG, and FLAC are supported.

Fields

Result variables

⏱ The file link is valid for 24 hours, after which the file is automatically deleted from the server.

"Edit Audio Metadata" Action

Edits the tags (title, artist, album, etc.) of a local audio file.

Fields

Fill in at least one field, or check at least one "Clear" checkbox.

Result variables

⏱ The file link is valid for 24 hours, after which the file is automatically deleted from the server.

Execution Status and Error Handling

Every action in the "File Processing" block — all 15, including the newer audio actions — always writes two additional service variables alongside its own result:

Here, prefix is the same variable name you entered in the "Save result to variable" field (or "Result prefix" for HTML → PDF/PNG).

This pairs well with a "Condition" block placed right after the "File Processing" block: check {{prefix.status}} == error, and if it matches, show the user an error message, route to a different part of the scenario, or send yourself a notification.

Example: after the "Extract audio from video" action with variable audio, add a "Condition" block checking {{audio.status}} equals error → on that branch, send the text "Couldn't process the video, please try a different file"; otherwise, continue the scenario as usual.