Uploading and downloading files

MadelineProto provides fully parallelized wrapper methods to upload and download files that support bot API file ids, direct upload by URL and file renaming.

Maximum file size is of 4 GB.

Example bot: downloadRenameBot.php - download files by URL and rename Telegram files using this async parallelized bot!

Bot API file IDs
Uploading & sending files
Uploading files
Reusing uploaded files
Renaming files
Downloading files
Getting progress

Sending files

To send photos and documents to someone, use the $MadelineProto->messages->sendMedia method, click on the link for more info.

All files will be uploaded asynchronously and in parallel, 20 chunks at a time for maximum performance (this value can be tweaked in the settings).

The required message parameter is the caption: it can contain URLs, mentions, bold and italic text, thanks to the parse_mode parameter, that enables markdown or HTML parsing.

The media parameter contains the file path and other info about the file.

It can contain lots of various objects, here are the most important:

Security notice

Be careful when calling methods with user-provided parameters: the upload function may be used to access and send any file.
To disable automatic uploads by file name (disabled by default), use the appropriate setting OR upload files manually.

inputMediaUploadedPhoto

$sentMessage = $MadelineProto->messages->sendMedia([
    'peer' => '@danogentili',
    'media' => [
        '_' => 'inputMediaUploadedPhoto',
        'file' => 'faust.jpg'
    ],
    'message' => '[This is the caption](https://t.me/MadelineProto)',
    'parse_mode' => 'Markdown'
]);

Can be used to upload photos: simply provide the photo’s file path in the file field, and optionally provide a ttl_seconds field to set the self-destruction period of the photo, even for normal chats. You can also provide a URL to the file field.

inputMediaUploadedDocument

$sentMessage = $MadelineProto->messages->sendMedia([
    'peer' => '@danogentili',
    'media' => [
        '_' => 'inputMediaUploadedDocument',
        'file' => 'video.mp4',
        'attributes' => [
            ['_' => 'documentAttributeVideo', 'round_message' => false, 'supports_streaming' => true]
        ]
    ],
    'message' => '[This is the caption](https://t.me/MadelineProto)',
    'parse_mode' => 'Markdown'
]);

Can be used to upload documents, videos, gifs, voice messages, round videos, round voice messages: simply provide the file’s file path in the file field, and optionally provide a ttl_seconds field to set the self-destruction period of the photo, even for normal chats.
You can also provide a URL to the file field.
To rename files, provide an Update or another already-uploaded Telegram file object to the file field. You can also (optionally) provide the file’s mime type in the mime_type field, generate it using mime_content_type($file_path); (tip: try using an unexpected mime type to make official clients crash ;).
Use the nosound_video field if the video does not have sound (gifs).
To actually set the document type, provide one or more DocumentAttribute objects to the attributes field:

documentAttributeFilename to send a document

$sentMessage = $MadelineProto->messages->sendMedia([
    'peer' => '@danogentili',
    'media' => [
        '_' => 'inputMediaUploadedDocument',
        'file' => 'file.txt',
        'attributes' => [
            ['_' => 'documentAttributeFilename', 'file_name' => 'document.txt']
        ]
    ],
    'message' => '[This is the caption](https://t.me/MadelineProto)',
    'parse_mode' => 'Markdown'
]);

documentAttributeImageSize to send a photo as document

$sentMessage = $MadelineProto->messages->sendMedia([
    'peer' => '@danogentili',
    'media' => [
        '_' => 'inputMediaUploadedDocument',
        'file' => 'file.jpg',
        'attributes' => [
            ['_' => 'documentAttributeImageSize'],
            ['_' => 'documentAttributeFilename', 'file_name' => 'image.jpg']
        ]
    ],
    'message' => '[This is the caption](https://t.me/MadelineProto)',
    'parse_mode' => 'Markdown'
]);

documentAttributeAnimated to send a gif

$sentMessage = $MadelineProto->messages->sendMedia([
    'peer' => '@danogentili',
    'media' => [
        '_' => 'inputMediaUploadedDocument',
        'file' => 'file.mp4',
        'attributes' => [
            ['_' => 'documentAttributeAnimated']
        ]
    ],
    'message' => '[This is the caption](https://t.me/MadelineProto)',
    'parse_mode' => 'Markdown'
]);

documentAttributeVideo to send a video

$sentMessage = $MadelineProto->messages->sendMedia([
    'peer' => '@danogentili',
    'media' => [
        '_' => 'inputMediaUploadedDocument',
        'file' => 'video.mp4',
        'attributes' => [
            ['_' => 'documentAttributeVideo', 'round_message' => false, 'supports_streaming' => true]
        ]
    ],
    'message' => '[This is the caption](https://t.me/MadelineProto)',
    'parse_mode' => 'Markdown'
]);

Set round_message to true to send a round message.
You might want to manually provide square w (width) and h (height) parameters to send round videos.

documentAttributeAudio to send an audio file

$sentMessage = $MadelineProto->messages->sendMedia([
    'peer' => '@danogentili',
    'media' => [
        '_' => 'inputMediaUploadedDocument',
        'file' => 'song.mp3',
        'attributes' => [
            ['_' => 'documentAttributeAudio', 'voice' => false, 'title' => 'This is magic', 'performer' => 'Daniil Gentili']
        ]
    ],
    'message' => '[This is the caption](https://t.me/MadelineProto)',
    'parse_mode' => 'Markdown'
]);

Set the voice parameter to true to send a voice message.

Uploading files

$MessageMedia = $MadelineProto->messages->uploadMedia([
    'media' => [
        '_' => 'inputMediaUploadedPhoto',
        'file' => 'faust.jpg'
    ],
]);

The file can be a file name, a URL, or a file uploaded by someone else (can be used to rename files).

You can also only upload a file, without actually sending it to anyone, storing only the file ID for later usage.

All files will be uploaded asynchronously and in parallel, 20 chunks at a time for maximum performance (this value can be tweaked in the settings).

The $MadelineProto->messages->uploadMedia function is a reduced version of the $MadelineProto->messages->sendMedia, that requires only a media parameter, with the media to upload (on normal users, the peer field should be populated with @me or another value).

The returned MessageMedia object can then be reused to resend the document using sendMedia.

$sentMessage = $MadelineProto->messages->sendMedia([
    'peer' => '@danogentili',
    'media' => $MessageMedia,
    'message' => '[This is the caption](https://t.me/MadelineProto)',
    'parse_mode' => 'Markdown'
]);

$MessageMedia can also be a Message (the media contained in the message will be sent), an Update (the media contained in the message contained in the update will be sent).

Reusing uploaded files

$MadelineProto->messages->uploadMedia and bot API file IDs do not allow you to modify the type of the file to send: however, MadelineProto provides methods that can generate a file object that can be resent with multiple file types.

$inputFile = $MadelineProto->upload('filename.mp4');

The file name can also be a URL.
More optional parameters are available, check the PHPDOC of the method in your IDE.
You can also upload a file from a stream (this is especially useful, for example, when downloading YouTube videos using youtube-dl with ffmpeg and async AMPHP CLI streams):

$inputFile = $MadelineProto->uploadFromStream($stream);

$stream - PHP resource or async AMPHP stream.

More optional parameters are available, check the PHPDOC of the method in your IDE.
You can also upload files from a callable:

$inputFile = $MadelineProto->uploadFromCallable($callable, $size, $mime);

$callable:
The callable must accept two parameters: int $offset, int $size
The callable must return a string with the contest of the file at the specified offset and size.

More optional parameters are available, check the PHPDOC of the method in your IDE.

You can also re-use a media received in a message or update, for example in the event handler:

$inputFile = $update;
$inputFile = $message;

The generated $inputFile can later be reused thusly:

$sentMessage = $MadelineProto->messages->sendMedia([
    'peer' => '@danogentili',
    'media' => [
        '_' => 'inputMediaUploadedDocument',
        'file' => $inputFile,
        'attributes' => [
            ['_' => 'documentAttributeFilename', 'file_name' => 'video.mp4']
        ]
    ],
    'message' => '[This is the caption](https://t.me/MadelineProto)',
    'parse_mode' => 'Markdown'
]);
$sentMessageVideo = $MadelineProto->messages->sendMedia([
    'peer' => '@danogentili',
    'media' => [
        '_' => 'inputMediaUploadedDocument',
        'file' => $inputFile,
        'attributes' => [
            ['_' => 'documentAttributeVideo', 'round_message' => false, 'supports_streaming' => true]
        ]
    ],
    'message' => '[This is the caption](https://t.me/MadelineProto)',
    'parse_mode' => 'Markdown'
]);

In this case, we’re reusing the same InputFile to send both a document and a video, without uploading the file twice.

The concept is easy: where you would usually provide a file path, simply provide $inputFile.

Renaming files

Files can be renamed by simply providing the $Update with the file to the sendMedia method thusly:

$sentMessage = $MadelineProto->messages->sendMedia([
    'peer' => '@danogentili',
    'media' => [
        '_' => 'inputMediaUploadedDocument',
        'file' => $Update,
        'attributes' => [
            ['_' => 'documentAttributeFilename', 'file_name' => $newName]
        ]
    ],
    'message' => '[This is the caption](https://t.me/MadelineProto)',
    'parse_mode' => 'Markdown'
]);

Downloading files

There are multiple download methods that allow you to download a file to a directory, to a file or to a stream.

Extracting download info

$info = $MadelineProto->getDownloadInfo($MessageMedia);

$MessageMedia can be a MessageMedia object or a bot API file ID.

You can also use getDownloadLink to obtain a direct download link for any file up to 4GB.

$info['ext'] - The file extension
$info['name'] - The file name, without the extension
$info['mime'] - The file mime type
$info['size'] - The file size

Getting a download link

To obtain a direct download link for any Telegram file up to 4GB, simply use getDownloadLink, for example:

<?php

if (!file_exists('madeline.php')) {
    copy('https://phar.madelineproto.xyz/madeline.php', 'madeline.php');
}
include 'madeline.php';

$MadelineProto = new \danog\MadelineProto\API('session.madeline');

// For bots
$MadelineProto->botLogin('token');

// For users
//$MadelineProto->start();

$botApiFileId = '...';
$fileName = '...';
$fileSize = 123..;
$mimeType = '...';


$link = $MadelineProto->getDownloadLink($botApiFileId, size: $fileSize, name: $fileName, mime: $mimeType);

Event handler example with bound methods:

use danog\MadelineProto\SimpleEventHandler;
use danog\MadelineProto\EventHandler\Filter\FilterCommand;
use danog\MadelineProto\EventHandler\Message;
use danog\MadelineProto\EventHandler\SimpleFilter\Incoming;

class MyEventHandler extends SimpleEventHandler
{
    /**
     * Gets a download link for any file up to 4GB!
     */
    #[FilterCommand('dl')]
    public function downloadLink(Incoming&Message $message): void
    {
        $reply = $message->getReply(Message::class);
        if (!$reply?->media) {
            $message->reply("This command must reply to a media message!");
            return;
        }
        $reply->reply("Download link: ".$reply->media->getDownloadLink());
    }
}

MyEventHandler::startAndLoop('bot.madeline')

$botApiFileId can be a MessageMedia object or a bot API file ID (files up to 4GB are supported!).

This method will work automatically only when running via web (apache/php-fpm).

The generated download $link will point to your own server, and the link will stream files directly to the browser (no temporary files will be created, 0 disk space will be used).

Getting a download link (CLI bots)

Only if running via CLI (or if URL rewriting is enabled on web), a second parameter must be provided with a URL to a download script hosted on a php-fpm/apache instance on the same machine:

<?php

if (!file_exists('madeline.php')) {
    copy('https://phar.madelineproto.xyz/madeline.php', 'madeline.php');
}
include 'madeline.php';

$MadelineProto = new \danog\MadelineProto\API('session.madeline');

// For bots
$MadelineProto->botLogin('token');

// For users
//$MadelineProto->start();

$botApiFileId = '...';
$fileName = '...';
$fileSize = 123..;
$mimeType = '...';


$link = $MadelineProto->getDownloadLink($botApiFileId, 'https://yourhost.com/dl.php', size: $fileSize, name: $fileName, mime: $mimeType);

Event handler example with bound methods:

use danog\MadelineProto\SimpleEventHandler;
use danog\MadelineProto\EventHandler\Filter\FilterCommand;
use danog\MadelineProto\EventHandler\Message;
use danog\MadelineProto\EventHandler\SimpleFilter\Incoming;

class MyEventHandler extends SimpleEventHandler
{
    /**
     * Gets a download link for any file up to 4GB!
     */
    #[FilterCommand('dl')]
    public function downloadLink(Incoming&Message $message): void
    {
        $reply = $message->getReply(Message::class);
        if (!$reply?->media) {
            $message->reply("This command must reply to a media message!");
            return;
        }
        $reply->reply("Download link: ".$reply->media->getDownloadLink('https://yourhost.com/dl.php'));
    }
}

MyEventHandler::startAndLoop('bot.madeline')

You can also pass your custom download link in the Files settings, instead.

The dl.php script must have the following content:

<?php

if (!file_exists('madeline.php')) {
    copy('https://phar.madelineproto.xyz/madeline.php', 'madeline.php');
}
include 'madeline.php';

\danog\MadelineProto\API::downloadServer('session.madeline');

Note that session.madeline must be logged into exactly the same user/bot used by the CLI userbot/bot.

To login the first time, simple open dl.php?login=1 in your browser: if the session is not logged in, a login prompt will be shown, otherwise the user/bot ID will be displayed.

The link will stream files directly to the browser (no temporary files will be created, 0 disk space will be used).

Downloading profile pictures

$info = $MadelineProto->getPropicInfo($Update);

$Update can be a Message object, an Update, or any value supported by getInfo.
The result (which is in the same format as getDownloadInfo) should the be passed to the download functions in order to download the profile picture.

$info['ext'] - The file extension
$info['name'] - The file name, without the extension
$info['mime'] - The file mime type
$info['size'] - The file size

Download to directory

$output_file_name = $MadelineProto->downloadToDir($MessageMedia, '/tmp/');

This downloads the given file to /tmp, and returns the full generated file path.

Note: if downloading files that will be re-downloaded by the user, use downloadToBrowser, instead: downloadToBrowser will avoid the creation of temporary files, streaming the file directly to the user.

You can also use getDownloadLink to obtain a direct download link for any file up to 4GB.

$MessageMedia can be either a Message, an Update, a MessageMedia object, or a bot API file ID.

Download to file

$output_file_name = $MadelineProto->downloadToFile($MessageMedia, '/tmp/myname.mp4');

You can also use getDownloadLink to obtain a direct download link for any file up to 4GB.

This downloads the given file to /tmp/myname.mp4, and returns the full file path.

$MessageMediacan be either a Message, an Update, a MessageMedia object, or a bot API file ID.

Download to stream

$MadelineProto->downloadToStream($MessageMedia, $stream);

This downloads the given file to the given resource or async AMPHP stream, the latter is especially useful for building an async HTTP file server with http-server.

$MessageMediacan be either a Message, an Update, a MessageMedia object, or a bot API file ID.

You can also use downloadToReturnedStream, which returns an amphp ReadableStream, instead:

$stream = $MadelineProto->downloadToReturnedStream($MessageMedia);

Download to callback

$MadelineProto->downloadToCallable($MessageMedia, $callable);

This downloads the given file to the callable. The callable must accept two parameters: string $payload, int $offset The callable will be called (possibly out of order, depending on the value of the $seekable (see PHPDOC)). The callable should return the number of written bytes.

$MessageMediacan be either a Message, an Update, a MessageMedia object, or a bot API file ID.

Download to http-server

$MadelineProto->downloadToResponse($MessageMedia, $request, $cb);

This downloads the given file, replying to the specified async http-server request.
Automatically supports HEAD requests and content-ranges for parallel and resumed downloads.

$MessageMedia can be either a Message, an Update, a MessageMedia object, or a bot API file ID.

$request is the Request object returned by http-server.

$cb is an optional parameter can be a callback for download progress, but it shouldn’t be used, the new FileCallback should be used instead

Download to browser

$MadelineProto->downloadToBrowser($MessageMedia, $cb);

You can also use getDownloadLink to obtain a direct download link for any file up to 4GB.

This downloads the given file to the browser, sending also information about the file’s type and size. Automatically supports HEAD requests and content-ranges for parallel and resumed downloads.

$MessageMedia can be either a Message, an Update, a MessageMedia object, or a bot API file ID.

$cb is an optional parameter can be a callback for download progress, but it shouldn’t be used, the new FileCallback should be used instead

Getting progress

To get the upload/download progress in real-time, use the \danog\MadelineProto\FileCallback class:

$peer = '@danogentili';
$sentMessage = $MadelineProto->messages->sendMedia([
    'peer' => $peer,
    'media' => [
        '_' => 'inputMediaUploadedDocument',
        'file' => new \danog\MadelineProto\FileCallback(
            'video.mp4',
            function ($progress, $speed, $time) use ($MadelineProto, $peer) {
                try {
                    $MadelineProto->messages->sendMessage(['peer' => $peer, 'message' => "Upload progress: $progress%\nSpeed: $speed mbps\nTime elapsed since start: $time"]);
                } catch (\Throwable $e) {}
            }
        ),
        'attributes' => [
            ['_' => 'documentAttributeVideo', 'round_message' => false, 'supports_streaming' => true]
        ]
    ],
    'message' => '[This is the caption](https://t.me/MadelineProto)',
    'parse_mode' => 'Markdown'
]);

$output_file_name = $MadelineProto->downloadToFile(
    $sentMessage,
    new \danog\MadelineProto\FileCallback(
        '/tmp/myname.mp4',
        function ($progress, $speed, $time) use ($MadelineProto, $peer) {
            try {
                $MadelineProto->messages->sendMessage(['peer' => $peer, 'message' => "Download progress: $progress%\nSpeed: $speed mbps\nTime elapsed since start: $time"]);
            } catch (\Throwable $e) {}
        }
    )
);

This will send the file video.mp4 to @danogentili: while uploading, he will receive progress messages Upload progress: 24% until the upload is complete; while downloading, he will receive progress messages Download progress: 34% until the download is complete.

You can also add two more parameters $speed, $time to the signature of the method to get a partial upload speed in mbps, along with the time elapsed since the start of the download.

A FileCallback object can be provided to uploadMedia, sendMedia, uploadProfilePicture, upload, upload_encrypted, download_to_*: the first parameter to its constructor must be the file path/object that is usually accepted by the function, the second must be a callable function or object.

You can also write your own callback class, just implement \danog\MadelineProto\FileCallbackInterface:

class MyCallback implements \danog\MadelineProto\FileCallbackInterface
{
    private $file;
    private $peer;
    private $MadelineProto;
    public function __construct($file, $peer, $MadelineProto)
    {
        $this->file = $file;
        $this->peer = $peer;
        $this->MadelineProto = $MadelineProto;
    }
    public function getFile()
    {
        return $this->file;
    }
    public function __invoke($progress, $speed, $time)
    {
        $this->MadelineProto->messages->sendMessage(['peer' => $this->peer, 'message' => 'Progress: '.$progress.'%']);
    }
}
$peer = '@danogentili';
$sentMessage = $MadelineProto->messages->sendMedia([
    'peer' => $peer,
    'media' => [
        '_' => 'inputMediaUploadedDocument',
        'file' => new MyCallback('video.mp4', $peer, $MadelineProto),
        'attributes' => [
            ['_' => 'documentAttributeVideo', 'round_message' => false, 'supports_streaming' => true]
        ]
    ],
    'message' => '[This is the caption](https://t.me/MadelineProto)',
    'parse_mode' => 'Markdown'
]);

$output_file_name = $MadelineProto->downloadToFile(
    $sentMessage,
    new MyCallback('/tmp/myname.mp4', $peer, $MadelineProto)
);

Bot API file IDs

$MessageMedia can even be a bot API file ID, generated by the bot API, or by MadelineProto:

Actual MessageMedia objects can also be converted to bot API file IDs like this:

$botAPI_file = $MadelineProto->MTProtoToBotAPI($MessageMedia);

$botAPI_file now contains a bot API message, to extract the file ID from it use the following code:

foreach (['audio', 'document', 'photo', 'sticker', 'video', 'voice', 'video_note'] as $type) {
    if (isset($botAPI_file[$type]) && is_array($botAPI_file[$type])) {
        $method = $type;
    }
}
$result['file_type'] = $method;
if ($result['file_type'] == 'photo') {
    $result['file_size'] = $botAPI_file[$method][0]['file_size'];
    if (isset($botAPI_file[$method][0]['file_name'])) {
        $result['file_name'] = $botAPI_file[$method][0]['file_name'];
        $result['file_id'] = $botAPI_file[$method][0]['file_id'];
    }
} else {
    if (isset($botAPI_file[$method]['file_name'])) {
        $result['file_name'] = $botAPI_file[$method]['file_name'];
    }
    if (isset($botAPI_file[$method]['file_size'])) {
        $result['file_size'] = $botAPI_file[$method]['file_size'];
    }
    if (isset($botAPI_file[$method]['mime_type'])) {
        $result['mime_type'] = $botAPI_file[$method]['mime_type'];
    }
    $result['file_id'] = $botAPI_file[$method]['file_id'];
}
if (!isset($result['mime_type'])) {
    $result['mime_type'] = 'application/octet-stream';
}
if (!isset($result['file_name'])) {
    $result['file_name'] = $result['file_id'].($method === 'sticker' ? '.webp' : '');
}

$result['file_id'] - Bot API file ID
$result['mime_type'] - Mime type
$result['file_type'] - File type: voice, video, video_note (round video), music, video, photo, sticker or document
$result['file_size'] - File size
$result['file_name'] - File name

Next section