Skip to main content

​
Methods Overview

MadelineProto provides access to all Telegram API methods through namespaced classes, making it easy to interact with the Telegram platform.

​
API Namespaces

All API methods are organized into namespaces that correspond to Telegram’s API structure.

​
Available Namespaces

​
messages
\danog\MadelineProto\Namespace\Messages
Message operations - sending, editing, deleting, forwarding
​
channels
\danog\MadelineProto\Namespace\Channels
Channel management - create, edit, join, leave channels
​
users
\danog\MadelineProto\Namespace\Users
User operations - get user info, full user data
​
contacts
\danog\MadelineProto\Namespace\Contacts
Contact management - add, delete, block, import contacts
​
account
\danog\MadelineProto\Namespace\Account
Account settings - privacy, profile, password, sessions
​
auth
\danog\MadelineProto\Namespace\Auth
Authentication - login, logout, sign up, 2FA
​
bots
\danog\MadelineProto\Namespace\Bots
Bot operations - inline queries, callback answers, commands
​
photos
\danog\MadelineProto\Namespace\Photos
Photo operations - upload, delete, update profile photos
​
upload
\danog\MadelineProto\Namespace\Upload
File upload operations
​
help
\danog\MadelineProto\Namespace\Help
Helper methods - get config, app update, support
​
payments
\danog\MadelineProto\Namespace\Payments
Payment operations - invoices, shipping, validation
​
stickers
\danog\MadelineProto\Namespace\Stickers
Sticker operations - create, add, remove sticker sets
​
phone
\danog\MadelineProto\Namespace\Phone
Phone call operations
​
stats
\danog\MadelineProto\Namespace\Stats
Statistics for channels and megagroups
​
folders
\danog\MadelineProto\Namespace\Folders
Chat folder operations
​
stories
\danog\MadelineProto\Namespace\Stories
Story operations (new feature)
​
premium
\danog\MadelineProto\Namespace\Premium
Premium features

​
Usage

​
In EventHandler

All namespaces are directly accessible: 
use danog\MadelineProto\EventHandler;
use danog\MadelineProto\EventHandler\Message;

class MyBot extends EventHandler
{
    public function onUpdateNewMessage(Message $message): void
    {
        // Access messages namespace
        $this->messages->sendMessage([
            'peer' => $message->chatId,
            'message' => 'Hello!',
        ]);
        
        // Access users namespace
        $user = $this->users->getFullUser(['id' => $message->senderId]);
        
        // Access channels namespace
        $this->channels->joinChannel(['channel' => '@mychannel']);
    }
}

​
In API Instance

use danog\MadelineProto\API;

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

// Send a message
$MadelineProto->messages->sendMessage([
    'peer' => '@username',
    'message' => 'Hello from MadelineProto!',
]);

// Get user info
$user = $MadelineProto->users->getFullUser(['id' => 'username']);

// Get channel info
$channel = $MadelineProto->channels->getFullChannel(['channel' => '@channel']);

​
Method Call Styles

​
Array Parameters

The traditional MTProto style: 
$this->messages->sendMessage([
    'peer' => $chatId,
    'message' => 'Hello',
    'parse_mode' => 'Markdown',
]);

​
Named Parameters (PHP 8.0+)

Cleaner syntax: 
$this->messages->sendMessage(
    peer: $chatId,
    message: 'Hello',
    parse_mode: 'Markdown'
);

​
Common Patterns

​
Sending Messages

// Simple text message
$this->messages->sendMessage([
    'peer' => $peer,
    'message' => 'Hello!',
]);

// With formatting
$this->messages->sendMessage([
    'peer' => $peer,
    'message' => '**Bold** and _italic_',
    'parse_mode' => 'Markdown',
]);

// With reply keyboard
$this->messages->sendMessage([
    'peer' => $peer,
    'message' => 'Choose:',
    'reply_markup' => [
        'inline_keyboard' => [[
            ['text' => 'Button', 'callback_data' => 'data'],
        ]],
    ],
]);

​
Getting Information

// Get user info
$user = $this->users->getFullUser(['id' => $userId]);

// Get channel info
$channel = $this->channels->getFullChannel(['channel' => $channelId]);

// Get chat info
$chat = $this->messages->getFullChat(['chat_id' => $chatId]);

​
Managing Channels

// Create channel
$channel = $this->channels->createChannel([
    'title' => 'My Channel',
    'about' => 'Channel description',
]);

// Join channel
$this->channels->joinChannel(['channel' => '@username']);

// Leave channel
$this->channels->leaveChannel(['channel' => $channelId]);

// Edit channel
$this->channels->editTitle([
    'channel' => $channelId,
    'title' => 'New Title',
]);

​
Managing Contacts

// Add contact
$this->contacts->addContact([
    'id' => $userId,
    'first_name' => 'John',
    'last_name' => 'Doe',
    'phone' => '+1234567890',
]);

// Delete contact
$this->contacts->deleteContacts(['id' => [$userId]]);

// Block user
$this->contacts->block(['id' => $userId]);

// Unblock user
$this->contacts->unblock(['id' => $userId]);

​
Error Handling

use danog\MadelineProto\RPCErrorException;

try {
    $this->messages->sendMessage([
        'peer' => $peer,
        'message' => 'Hello',
    ]);
} catch (RPCErrorException $e) {
    // Handle specific errors
    match ($e->rpc) {
        'PEER_ID_INVALID' => $this->logger('Invalid peer ID'),
        'MESSAGE_TOO_LONG' => $this->logger('Message is too long'),
        'FLOOD_WAIT_X' => $this->logger('Flood wait: ' . $e->rpc),
        default => throw $e,
    };
}

​
Pagination

Many methods support pagination: 
// Get messages with pagination
$messages = $this->messages->getHistory([
    'peer' => $peer,
    'offset_id' => 0,
    'offset_date' => 0,
    'add_offset' => 0,
    'limit' => 100,
    'max_id' => 0,
    'min_id' => 0,
]);

// Get channel participants with pagination
$participants = $this->channels->getParticipants([
    'channel' => $channelId,
    'filter' => ['_' => 'channelParticipantsRecent'],
    'offset' => 0,
    'limit' => 200,
]);

​
File Operations

See Files Settings for configuration. 
// Upload file
$media = $this->messages->uploadMedia([
    'media' => [
        '_' => 'inputMediaUploadedDocument',
        'file' => '/path/to/file.pdf',
    ],
]);

// Send media
$this->messages->sendMedia([
    'peer' => $peer,
    'media' => $media,
]);

​
Async Operations

All methods are async by default in MadelineProto: 
use function Amp\async;
use function Amp\Future\await;

// Run multiple operations in parallel
$futures = [
    async($this->messages->sendMessage(...), [
        'peer' => $peer1,
        'message' => 'Message 1',
    ]),
    async($this->messages->sendMessage(...), [
        'peer' => $peer2,
        'message' => 'Message 2',
    ]),
];

// Wait for all to complete
$results = await($futures);

​
Best Practices

  1. Use type hints for better IDE support
  2. Handle RPC errors appropriately
  3. Respect rate limits (flood wait)
  4. Use async for concurrent operations
  5. Cache peer information when possible
  6. Validate input before API calls
  7. Use appropriate namespaces for clarity

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us