Laravel MAX Bot

Laravel пакет для MAX messenger Bot API.

Version compatibility

Installation

composer require dizvestnov/laravel-max-bot

Опубликовать конфиг:

php artisan vendor:publish --tag=max-bot-config

Добавить в .env:

MAX_BOT_TOKEN=your_bot_token_here

Configuration

Основные параметры config/max-bot.php:

Usage — sending a message

use Dizvestnov\LaravelMaxBot\Messages\OutgoingMessage;
use Dizvestnov\LaravelMaxBot\Keyboard;
use Dizvestnov\LaravelMaxBot\Buttons\CallbackButton;

OutgoingMessage::create('Привет!')
    ->to($userId)
    ->withKeyboard(
        Keyboard::make()
            ->row(
                CallbackButton::make('Да', 'yes'),
                CallbackButton::make('Нет', 'no'),
            )
    )
    ->markdown()
    ->send();

Or via facade:

use Dizvestnov\LaravelMaxBot\Facades\MaxBot;

MaxBot::sendMessage([
    'recipient' => ['user_id' => $userId],
    'text'      => 'Hello!',
]);

Usage — webhook

Add to .env:

MAX_BOT_WEBHOOK_PATH=max-bot/webhook
MAX_BOT_WEBHOOK_SECRET=your_hmac_secret

Set webhook via Artisan:

php artisan max-bot:webhook:set https://yourdomain.com/max-bot/webhook

Listen for events in EventServiceProvider:

protected $listen = [
    \Dizvestnov\LaravelMaxBot\Events\MessageReceived::class => [
        \App\Listeners\HandleIncomingMessage::class,
    ],
];

// App\Listeners\HandleIncomingMessage
public function handle(MessageReceived $event): void
{
    $text   = $event->getText();
    $userId = $event->getSenderId();

    OutgoingMessage::create('You said: ' . $text)->to($userId)->send();
}

Usage — long polling

php artisan max-bot:poll

Usage — conversation state

use Dizvestnov\LaravelMaxBot\Conversation\StateManager;

class RegistrationFlow
{
    public function __construct(private StateManager $state) {}

    public function handle(MessageReceived $event): void
    {
        $userId  = $event->getSenderId();
        $current = $this->state->getState($userId);

        if ($current === null) {
            $this->state->setState($userId, 'waiting_name');
            OutgoingMessage::create('Как вас зовут?')->to($userId)->send();
            return;
        }

        if ($current === 'waiting_name') {
            $this->state->mergeData($userId, ['name' => $event->getText()]);
            $this->state->setState($userId, 'waiting_email');
            OutgoingMessage::create('Ваш email?')->to($userId)->send();
        }
    }
}

Usage — keyboard buttons

use Dizvestnov\LaravelMaxBot\Keyboard;
use Dizvestnov\LaravelMaxBot\Buttons\CallbackButton;
use Dizvestnov\LaravelMaxBot\Buttons\LinkButton;
use Dizvestnov\LaravelMaxBot\Buttons\RequestContactButton;

$keyboard = Keyboard::make()
    ->row(
        CallbackButton::make('Callback', 'payload'),
        LinkButton::make('Website', 'https://example.com'),
    )
    ->row(
        RequestContactButton::make('Share Contact'),
    );

Artisan commands

Testing

Mock MaxBotClientInterface in your tests:

use Dizvestnov\LaravelMaxBot\Contracts\MaxBotClientInterface;

$this->mock(MaxBotClientInterface::class, function ($mock) {
    $mock->shouldReceive('sendMessage')
        ->once()
        ->andReturn(['message_id' => 'test-id']);
});

License

MIT