README

BotMan driver for MAX Messenger. Build chatbots for MAX using the BotMan framework — just like you would for Telegram, Facebook, or Slack.

Features

Text messages, callback buttons, bot started events
Incoming media: images, video, audio, files, locations
Outgoing media: images, video, audio, files, locations
Inline keyboards (BotMan Question/Button or fluent MaxInlineKeyboard builder)
Conversations with interactive button replies
Typing indicator .- Webhook signature verification (X-Max-Bot-Api-Secret)
Lifecycle events (message_edited, bot_added, user_removed, etc.)
Laravel auto-discovery & Artisan commands

Requirements

PHP 8.1+
BotMan 2.x
Laravel 10/11 (optional, for ServiceProvider and artisan commands)

Installation

composer require xologie/botman-driver-max

Laravel

The service provider is auto-discovered via composer.json extra. Publish the config:

php artisan vendor:publish --provider="BotMan\Drivers\Max\Providers\MaxServiceProvider"

BotMan Studio

If using BotMan Studio, the driver is auto-discovered via discovery.json. No manual setup needed.

Standalone (without Laravel)

use BotMan\BotMan\Drivers\DriverManager;
use BotMan\Drivers\Max\MaxDriver;

DriverManager::loadDriver(MaxDriver::class);

Configuration

Add to your .env:

MAX_BOT_TOKEN=your-bot-token
MAX_WEBHOOK_SECRET=optional-secret
MAX_WEBHOOK_URL=https://your-domain.com/botman

Variable	Required	Description
`MAX_BOT_TOKEN`	Yes	Bot token from @MasterBot
`MAX_WEBHOOK_SECRET`	No	Secret for webhook verification via `X-Max-Bot-Api-Secret` header
`MAX_WEBHOOK_URL`	No	Default URL for artisan webhook commands
`MAX_THROW_HTTP_EXCEPTIONS`	No	Throw exceptions on API errors (default: `false`)

Bot Commands

To configure bot menu commands, add them to your published config/botman/max.php:

'commands' => [
    ['name' => 'help', 'description' => 'Show available commands'],
    ['name' => 'start', 'description' => 'Start the bot'],
],

Then apply them:

php artisan botman:max:commands

Usage

Echo Bot

$botman->hears('{message}', function ($bot, $message) {
    $bot->reply('You said: ' . $message);
});

Handling /start

The bot_started webhook event is automatically mapped to the /start text command:

$botman->hears('/start', function ($bot) {
    $bot->reply('Welcome! I am a MAX bot.');
});

Questions with Inline Buttons

use BotMan\BotMan\Messages\Outgoing\Question;
use BotMan\BotMan\Messages\Outgoing\Actions\Button;

$question = Question::create('What would you like to do?')
    ->addButton(Button::create('Order')->value('order'))
    ->addButton(Button::create('Help')->value('help'));

$botman->hears('menu', function ($bot) use ($question) {
    $bot->ask($question, function ($answer) {
        $value = $answer->getValue();
        // Handle 'order' or 'help'
    });
});

Conversations

use BotMan\BotMan\Messages\Conversations\Conversation;

class OnboardingConversation extends Conversation
{
    public function askName()
    {
        $this->ask('What is your name?', function ($answer) {
            $this->say('Nice to meet you, ' . $answer->getText());
        });
    }

    public function run()
    {
        $this->askName();
    }
}

$botman->hears('/start', function ($bot) {
    $bot->startConversation(new OnboardingConversation);
});

MaxInlineKeyboard (Fluent API)

For more control over keyboard layout, use the fluent builder:

use BotMan\Drivers\Max\Extensions\MaxInlineKeyboard;
use BotMan\Drivers\Max\Extensions\MaxKeyboardButton;

$keyboard = MaxInlineKeyboard::create()
    ->addRow(
        MaxKeyboardButton::create('Yes')->callbackData('yes'),
        MaxKeyboardButton::create('No')->callbackData('no')
    )
    ->addRow(
        MaxKeyboardButton::create('Website')->url('https://example.com')
    );

$botman->hears('vote', function ($bot) use ($keyboard) {
    $bot->reply('Cast your vote:', $keyboard->toArray());
});

Button types: callbackData(), url(), requestContact(), requestGeoLocation().

Driver Restriction

Limit a listener to MAX only:

use BotMan\Drivers\Max\MaxDriver;

$botman->hears('max only', function ($bot) {
    $bot->reply('This only works in MAX!');
})->driver(MaxDriver::class);

Receiving Attachments

$botman->receivesImages(function ($bot, $images) {
    foreach ($images as $image) {
        $bot->reply('Image: ' . $image->getUrl());
    }
});

$botman->receivesLocation(function ($bot, $location) {
    $bot->reply("Lat: {$location->getLatitude()}, Lng: {$location->getLongitude()}");
});

Also available: receivesVideos(), receivesAudio(), receivesFiles().

Sending Attachments

use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;
use BotMan\BotMan\Messages\Attachments\Image;

$message = OutgoingMessage::create('Check this out!')
    ->withAttachment(new Image('https://example.com/photo.jpg'));

$botman->hears('photo', function ($bot) use ($message) {
    $bot->reply($message);
});

Extended User Data

The driver returns an extended User object with MAX-specific methods:

$botman->hears('whoami', function ($bot) {
    $user = $bot->getUser();
    $bot->reply('Name: ' . $user->getFullName());
    $bot->reply('Username: ' . $user->getMaxUsername());
});

Events

Listen to MAX lifecycle events:

$botman->on('bot_added', function ($payload, $bot) {
    // Bot was added to a chat
});

$botman->on('message_edited', function ($payload, $bot) {
    // A message was edited
});

Available events: message_edited, message_removed, bot_added, bot_removed, user_added, user_removed, chat_title_changed.

Artisan Commands

Command	Description
`php artisan botman:max:register`	Register the webhook
`php artisan botman:max:unregister`	Remove the webhook
`php artisan botman:max:webhooks`	List all registered webhooks
`php artisan botman:max:commands`	Set bot menu commands

Options for register/unregister:

php artisan botman:max:register --url=https://your-domain.com/botman
php artisan botman:max:unregister --url=https://your-domain.com/botman

Drivers

Driver	Handles
`MaxDriver`	Text messages, callbacks, bot_started
`MaxImageDriver`	Incoming images
`MaxVideoDriver`	Incoming videos
`MaxAudioDriver`	Incoming audio
`MaxFileDriver`	Incoming files
`MaxLocationDriver`	Incoming locations

Testing

composer test

License

MIT

xologie / botman-driver-max

Maintainers

Package info

Statistics

Security