MadelineProto is an async PHP client API for the Telegram MTProto protocol, built for PHP developers who need to interact with Telegram the way the official apps do, without going through the Telegram Bot API.

What it is

MadelineProto is an async PHP client library for Telegram's MTProto protocol, created by Daniil Gentili and released under the AGPL-3.0 licence. It logs in either with a phone number over the MTProto API, or with a bot token over the MTProto API with no Bot API involved at all. The library is fully async, built on amphp, and is approved by Telegram. It sits in the Infrastructure & Operations / Messaging & Event Streaming category, with documentation hosted separately at docs.madelineproto.xyz and community support in the @MadelineProto channel and the @pwrtelegramgroup support group.

The concrete problem it solves is the Bot API abstraction layer. Where the Bot API offers a restricted, server-side surface, MadelineProto connects as a client, so the same code can act as a user account or as a bot, and can reach features the Bot API does not expose. It also replaces hand-written MTProto work: protocol methods are exposed as callable PHP methods such as messages->sendMessage(peer:, message:), channels->joinChannel(channel:) and messages->importChatInvite(hash:), and RPC failures surface as typed exceptions like \danog\MadelineProto\RPCErrorException.

Key capabilities

• Phone-number login (MTProto API) or bot-token login (MTProto API), with no Bot API involved.
• Fully async execution on amphp, documented under ASYNC.html.
• Callable coverage of MTProto methods, including messages->sendMessage, channels->joinChannel and messages->importChatInvite.
• Voice-over-IP and calls, indicated by the calls topic and by magnaluna webradio, a multifeatured Telegram VoIP webradio built on the library.
• Inline bots and userbots, as shown by pipesbot.php, which creates inline bots and drives other inline bots via a userbot.
• File handling: downloadRenameBot.php downloads files by URL and renames Telegram files in parallel, while bot.php obtains download links for any file and illustrates filters, updates and Telegram Stories.
• Secret chats, via secret_bot.php; plus proxy support, ->logger() output to MadelineProto.log, and RPC error reporting.

Who uses it and how

• Bot developers who need more than the Bot API exposes: bot.php covers filters, updates, download links and Telegram Stories.
• Userbot and inline-bot builders, for whom pipesbot.php chains inline bots together through a user account.
• Media tooling authors: @tgstories_dl_bot downloads any Telegram Story, and the download-and-rename bot parallelises bulk file work.
• VoIP and streaming projects, such as the magnaluna webradio.
• Individual developers and small teams running a single session: the README walks through creating an instance and running it in a browser or a console, with errors and the MadelineProto.log file sent to the support group when something fails.

Getting started

Create an instance with new \danog\MadelineProto\API('session.madeline'), call $MadelineProto->start(), and then call MTProto methods on it; the README suggests running the sample in a browser or in a console. Setup details, including obtaining permission to use the Telegram API and the available login flows, are documented at docs.madelineproto.xyz in CREATING_A_CLIENT.html and LOGIN.html.

How it compares

No paid products are listed as being replaced by this project, and no competing MTProto client is named in the facts, so MadelineProto stands alone in this registry as the PHP entry for Telegram MTProto access. Several of its core components have been factored out as standalone libraries, including danog/async-orm, danog/loop, danog/ipc, danog/better-prometheus, danog/dns-over-https, danog/telegram-entities, danog/tg-file-decoder and danog/tg-dialog-id, which can be adopted independently of the client.

When to use it — and when not to

A self-hoster runs the PHP runtime, keeps the session file and the generated MadelineProto.log, and holds the login credentials, whether a phone number or a bot token, plus the Telegram API permission the documentation describes. The AGPL-3.0 licence is copyleft, which constrains closed-source redistribution, and the project carries 75 open issues with documentation living off-repository, so teams wanting a managed service or a single self-contained README should look elsewhere. Projects that only need plain Bot API behaviour will find this library heavier than necessary, since its whole point is to bypass that API.

<?php

// PHP 8.2+ is required.

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

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

$me = $MadelineProto->getSelf();

$MadelineProto->logger($me);

if (!$me['bot']) {
    $MadelineProto->messages->sendMessage(peer: '@stickeroptimizerbot', message: "/start");

    $MadelineProto->channels->joinChannel(channel: '@MadelineProto');

    try {
        $MadelineProto->messages->importChatInvite(hash: 'https://t.me/+Por5orOjwgccnt2w');
    } catch (\danog\MadelineProto\RPCErrorException $e) {
        $MadelineProto->logger($e);
    }
}
$MadelineProto->echo('OK, done!');