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).