Simple Bot Example

A minimal bot implementation showing the basics of MadelineProto event handling

This example demonstrates the simplest possible MadelineProto bot. It’s perfect for getting started and understanding the core concepts.

Complete Code

Here’s the full working example from simpleBot.php:

<?php declare(strict_types=1);

// Simple example bot.
// PHP 8.2.4+ is required.

// Run via CLI (recommended: `screen php bot.php`) or via web.

// To reduce RAM usage, follow these instructions: https://docs.madelineproto.xyz/docs/DATABASE.html

use danog\MadelineProto\EventHandler\Attributes\Handler;
use danog\MadelineProto\EventHandler\Message;
use danog\MadelineProto\EventHandler\Plugin\RestartPlugin;
use danog\MadelineProto\EventHandler\SimpleFilter\Incoming;
use danog\MadelineProto\SimpleEventHandler;

// Load via composer (RECOMMENDED, see https://docs.madelineproto.xyz/docs/INSTALLATION.html#composer-from-scratch)
if (file_exists('vendor/autoload.php')) {
    require_once 'vendor/autoload.php';
} else {
    // Otherwise download an !!! alpha !!! version of MadelineProto via madeline.php
    if (!file_exists('madeline.php')) {
        copy('https://phar.madelineproto.xyz/madeline.php', 'madeline.php');
    }
    require_once 'madeline.php';
}

class BasicEventHandler extends SimpleEventHandler
{
    // !!! Change this to your username !!!
    public const ADMIN = "@me";

    /**
     * Get peer(s) where to report errors.
     */
    public function getReportPeers()
    {
        return [self::ADMIN];
    }

    /**
     * Returns a set of plugins to activate.
     *
     * See here for more info on plugins: https://docs.madelineproto.xyz/docs/PLUGINS.html
     */
    public static function getPlugins(): array
    {
        return [
            // Offers a /restart command to admins that can be used to restart the bot, applying changes.
            // Make sure to run in a bash while loop when running via CLI to allow self-restarts.
            RestartPlugin::class,
        ];
    }

    /**
     * Handle incoming updates from users, chats and channels.
     */
    #[Handler]
    public function handleMessage(Incoming&Message $message): void
    {
        // Code that uses $message...
        // See the following pages for more examples and documentation:
        // - https://github.com/danog/MadelineProto/blob/v8/examples/bot.php
        // - https://docs.madelineproto.xyz/docs/UPDATES.html
        // - https://docs.madelineproto.xyz/docs/FILTERS.html
        // - https://docs.madelineproto.xyz/
    }
}

BasicEventHandler::startAndLoop('bot.madeline');

Key Concepts

Event Handler Class

The bot extends SimpleEventHandler, which provides a simplified interface for handling Telegram updates:

class BasicEventHandler extends SimpleEventHandler
{
    public const ADMIN = "@me"; // Change to your username
}

Always change the ADMIN constant to your Telegram username. This is where error reports will be sent.

Message Handler

The #[Handler] attribute marks methods that handle specific update types:

#[Handler]
public function handleMessage(Incoming&Message $message): void
{
    // Your bot logic here
}

The Incoming&Message type intersection ensures only incoming messages are processed, filtering out outgoing messages automatically.

Error Reporting

The getReportPeers() method specifies where errors should be sent:

public function getReportPeers()
{
    return [self::ADMIN];
}

Built-in Plugins

The RestartPlugin provides a /restart command for admins:

public static function getPlugins(): array
{
    return [
        RestartPlugin::class,
    ];
}

When using the restart plugin, run your bot in a while loop: while true; do php bot.php; done

Running the Bot

Via CLI (Recommended)

Run in a screen session for persistence:

screen php simpleBot.php

Or with auto-restart:

while true; do php simpleBot.php; done

Via Web

Simply access the PHP file through your web server. The bot will run in the background.

Next Steps

• See Full Bot Example for advanced features
• Learn about Filters to handle specific message types
• Explore Plugins to extend functionality