Login Methods

Authenticate your MadelineProto client as a bot or user account with various login flows

Overview

MadelineProto supports multiple authentication methods for both bots and user accounts. The login flow depends on your use case and account type.

Bot Login

The simplest login method uses a bot token obtained from @BotFather:

use danog\MadelineProto\API;

$MadelineProto = new API('bot.madeline');
$MadelineProto->botLogin('YOUR_BOT_TOKEN');

Bot Login with Event Handler

For bots using event handlers, use the startAndLoopBot method:

use danog\MadelineProto\SimpleEventHandler;

class MyBot extends SimpleEventHandler
{
    // Your event handler methods
}

// Start bot and event loop
MyBot::startAndLoopBot('bot.madeline', 'YOUR_BOT_TOKEN');

This method from EventHandler.php:171:

• Initializes the API client
• Performs bot authentication
• Starts the event handler loop
• Sets up error reporting

User Login (Phone Number)

User accounts require a multi-step authentication process:

Step 1: Send Code

$MadelineProto = new API('user.madeline');
$authorization = $MadelineProto->phoneLogin('[phone]');

The phoneLogin method (Wrappers/Login.php:192):

• Sends an SMS/Telegram code to the phone number
• Returns authorization info
• Sets login state to API::WAITING_CODE

Step 2: Complete Login

// User enters the code received via SMS/Telegram
$code = readline('Enter code: ');

$authorization = $MadelineProto->completePhoneLogin($code);

Handling 2FA

If two-factor authentication is enabled:

if ($authorization['_'] === 'account.password') {
    $password = readline('Enter 2FA password: ');
    $authorization = $MadelineProto->complete2faLogin($password);
}

From Wrappers/Login.php:334, the complete2faLogin method:

• Verifies the 2FA password
• Completes the authentication process
• Updates login state to API::LOGGED_IN

Handling Signup

If the phone number is not registered:

if ($authorization['_'] === 'account.needSignup') {
    $firstName = readline('Enter first name: ');
    $lastName = readline('Enter last name (optional): ');
    
    $authorization = $MadelineProto->completeSignup($firstName, $lastName);
}

QR Code Login

For user accounts, MadelineProto supports QR code login:

$qrCode = $MadelineProto->qrLogin();

if ($qrCode) {
    // Display QR code to user
    echo "Scan this QR code: " . $qrCode->getQrCodeLink() . "\n";
    
    // Wait for login
    $MadelineProto->waitQrLogin();
}

The qrLogin method (Wrappers/Login.php:92):

• Generates a login QR code
• Returns a LoginQrCode object with:
  • getQrCodeLink(): The tg://login?token=... URL
  • isExpired(): Check if QR code is still valid
  • getExpiry(): Get expiration timestamp

QR codes expire after a certain period. Check isExpired() and regenerate if needed.

Login States

MadelineProto tracks the authentication state using constants from API.php:56-90:

NOT_LOGGED_IN · int

No authentication has been performed

WAITING_CODE · int

Waiting for SMS/Telegram login code

WAITING_SIGNUP · int

Phone number not registered, signup required

WAITING_PASSWORD · int

Waiting for 2FA password

LOGGED_IN · int

Successfully authenticated

LOGGED_OUT · int

Logged out, session will be deleted

Authorization Import/Export

Export Authorization

Export the authorization key for backup or multi-DC scenarios:

[$dcId, $authKey] = $MadelineProto->exportAuthorization();

From Wrappers/Login.php:301, this returns:

• $dcId: The datacenter ID
• $authKey: The authorization key (keep this secure!)

Import Authorization

Import a previously exported authorization:

$authorization = [
    $dcId => $authKey
];

$MadelineProto->importAuthorization($authorization, $dcId);

Authorization keys are sensitive credentials. Store them securely and never commit them to version control.

2FA Management

Update two-factor authentication settings:

// Enable 2FA
$MadelineProto->update2fa([
    'new_password' => 'secure_password',
    'email' => '[e-mail]',
    'hint' => 'My password hint'
]);

// Change password
$MadelineProto->update2fa([
    'password' => 'old_password',
    'new_password' => 'new_secure_password'
]);

// Disable 2FA
$MadelineProto->update2fa([
    'password' => 'current_password',
    'new_password' => ''
]);

Logout

Properly log out and invalidate the session:

$MadelineProto->logout();

This method (Wrappers/Login.php:162):

• Calls auth.logOut on the API
• Sets login state to API::LOGGED_OUT
• Stops the event handler if running
• Stops the IPC server

Complete Login Example

Here’s a complete user login flow:

use danog\MadelineProto\API;
use danog\MadelineProto\Settings;

$settings = new Settings;
$settings->getAppInfo()
    ->setApiId(12345)
    ->setApiHash('your_api_hash');

$MadelineProto = new API('user.madeline', $settings);

// Start phone login
$authorization = $MadelineProto->phoneLogin('[phone]');

// Get code from user
$code = readline('Enter code: ');
$authorization = $MadelineProto->completePhoneLogin($code);

// Handle 2FA if enabled
if ($authorization['_'] === 'account.password') {
    echo "2FA enabled. Hint: " . ($authorization['hint'] ?? 'none') . "\n";
    $password = readline('Enter password: ');
    $authorization = $MadelineProto->complete2faLogin($password);
}

// Handle signup if needed
if ($authorization['_'] === 'account.needSignup') {
    $firstName = readline('Enter first name: ');
    $authorization = $MadelineProto->completeSignup($firstName);
}

echo "Logged in successfully!\n";

Next Steps

Event Handlers

Set up event handlers to process updates

Async Operations

Understand asynchronous programming in MadelineProto