[opensourcedex]

MadelineProto is a free, open source messaging & event streaming project written in PHP and released under AGPL-3.0. It has 3,551 GitHub stars, 931 forks and 75 open issues, and was last pushed 11 hours ago. On this registry it ranks #6 of 18 tracked projects in Messaging & Event Streaming, with 5 head-to-head comparisons available. It gained 26 stars over the last 30 tracked days.

What is MadelineProto?

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.

project readme (upstream, from github) — read inline

MadelineProto, a PHP MTProto telegram client

Created by Daniil Gentili

#StandWithUkraine 🇺🇦

Do join the official channel, @MadelineProto and the support groups!

Approved by Telegram!

What's this?

This library can be used to easily interact with Telegram without the bot API, just like the official apps.

It can login with a phone number (MTProto API), or with a bot token (MTProto API, no bot API involved!).

It is now fully async!

Getting started (now fully async!)

<?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!');

Try running this code in a browser or in a console!

Tip: if you receive an error (or nothing), send us the error message and the MadelineProto.log file that was created in the same directory (if running from a browser).

Made with MadelineProto

The following open source projects were created using MadelineProto: you can directly install them, or explore the source code as direct examples on how to use MadelineProto's many features!

Want to add your own open-source project to this list? Click here!

Some of MadelineProto's core components are also available as separate, standalone libraries:

Documentation

Frequently asked questions

Is MadelineProto free to use?

MadelineProto is open source under the AGPL-3.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does MadelineProto do?

Async PHP client API for the telegram MTProto protocol

What is MadelineProto written in?

MadelineProto is primarily written in PHP. Its source is publicly available at https://github.com/danog/MadelineProto, and it has 3,551 GitHub stars.