PHPackages                             dizvestnov/laravel-max-bot - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. dizvestnov/laravel-max-bot

ActiveLibrary[API Development](/categories/api)

dizvestnov/laravel-max-bot
==========================

Laravel package for MAX messenger Bot API

v3.0.1(3mo ago)213↓88.9%MITPHPPHP ^8.2CI passing

Since Apr 14Pushed 3mo agoCompare

[ Source](https://github.com/dizvestnov/laravel-max-bot)[ Packagist](https://packagist.org/packages/dizvestnov/laravel-max-bot)[ RSS](/packages/dizvestnov-laravel-max-bot/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (11)Versions (8)Used By (0)

Laravel MAX Bot
===============

[](#laravel-max-bot)

[![Tests](https://github.com/dizvestnov/laravel-max-bot/actions/workflows/tests.yml/badge.svg)](https://github.com/dizvestnov/laravel-max-bot/actions/workflows/tests.yml)[![PHP](https://camo.githubusercontent.com/8bc1bbc7ba8a54764de253e53b89ce09f184ce093ed03fe695f945956cb054c4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f64697a766573746e6f762f6c61726176656c2d6d61782d626f74)](https://packagist.org/packages/dizvestnov/laravel-max-bot)[![License](https://camo.githubusercontent.com/2e7c1f339cf897937607960aab1f13207ad42e7d3f4e2138b97ee30eddbcdf65/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f64697a766573746e6f762f6c61726176656c2d6d61782d626f74)](LICENSE)

Laravel-пакет для работы с [MAX messenger](https://max.ru) Bot API.

---

Совместимость
-------------

[](#совместимость)

ВеткаLaravelPHPTestbench1.x8, 97.4, 8.06, 73.x12, 138.2, 8.3, 8.410, 11---

Установка
---------

[](#установка)

```
composer require dizvestnov/laravel-max-bot
```

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

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

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

```
MAX_BOT_TOKEN=ваш_токен_бота
```

Токен выдаётся при создании бота через @MaxBotFather в MAX.

---

Настройка
---------

[](#настройка)

Файл `config/max-bot.php` после публикации:

```
return [
    'token' => env('MAX_BOT_TOKEN', ''),

    'http' => [
        'base_uri' => env('MAX_BOT_BASE_URI', 'https://platform-api.max.ru'),
        'timeout'  => (int) env('MAX_BOT_TIMEOUT', 30),
        'retry'    => [
            'times' => 3,
            'sleep' => 100, // базовая задержка в мс (экспоненциальный backoff)
        ],
    ],

    'webhook' => [
        'secret'  => env('MAX_BOT_WEBHOOK_SECRET', null),
        'version' => env('MAX_BOT_WEBHOOK_VERSION', null),
        'route'   => [
            'enabled'    => true,
            'path'       => env('MAX_BOT_WEBHOOK_PATH', 'max-bot/webhook'),
            'middleware' => ['api'],
        ],
    ],

    'queue' => [
        'enabled'    => (bool) env('MAX_BOT_QUEUE_ENABLED', false),
        'connection' => env('MAX_BOT_QUEUE_CONNECTION', null),
        'queue'      => env('MAX_BOT_QUEUE_NAME', 'default'),
    ],
];
```

### Переменные окружения

[](#переменные-окружения)

ПеременнаяПо умолчаниюОписание`MAX_BOT_TOKEN`—Токен бота (обязательно)`MAX_BOT_BASE_URI``https://platform-api.max.ru`Базовый URL API`MAX_BOT_TIMEOUT``30`Таймаут HTTP-запросов (сек)`MAX_BOT_WEBHOOK_SECRET``null`HMAC-секрет для проверки подписи`MAX_BOT_WEBHOOK_PATH``max-bot/webhook`URL-путь для вебхука`MAX_BOT_QUEUE_ENABLED``false`Обрабатывать обновления через очередь`MAX_BOT_QUEUE_CONNECTION``null`Соединение очереди (null = дефолтное)`MAX_BOT_QUEUE_NAME``default`Имя очереди---

Отправка сообщений
------------------

[](#отправка-сообщений)

### Fluent-builder (рекомендуется)

[](#fluent-builder-рекомендуется)

```
use Dizvestnov\LaravelMaxBot\Messages\OutgoingMessage;

// Простое текстовое сообщение пользователю
OutgoingMessage::create('Привет!')
    ->to($userId)
    ->send();

// Сообщение в чат
OutgoingMessage::create('Всем привет!')
    ->inChat($chatId)
    ->send();

// Markdown-форматирование
OutgoingMessage::create('**Жирный** и _курсив_')
    ->to($userId)
    ->markdown()
    ->send();

// HTML-форматирование
OutgoingMessage::create('Жирный')
    ->to($userId)
    ->html()
    ->send();

// Ответ на конкретное сообщение
OutgoingMessage::create('Ответ')
    ->to($userId)
    ->replyTo($messageId)
    ->send();
```

### Через фасад (низкоуровневый доступ)

[](#через-фасад-низкоуровневый-доступ)

```
use Dizvestnov\LaravelMaxBot\Facades\MaxBot;

MaxBot::sendMessage([
    'recipient' => ['user_id' => $userId],
    'text'      => 'Привет!',
]);
```

---

Клавиатуры и кнопки
-------------------

[](#клавиатуры-и-кнопки)

### Типы кнопок

[](#типы-кнопок)

КлассОписание`CallbackButton`Callback-кнопка с payload`LinkButton`Ссылка на URL`RequestContactButton`Запрос контакта пользователя`RequestGeoLocationButton`Запрос геолокации`MessageButton`Кнопка, отправляющая текст в чат`ClipboardButton`Копирует текст в буфер обмена### Пример клавиатуры

[](#пример-клавиатуры)

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

$keyboard = Keyboard::make()
    ->row(
        CallbackButton::make('Да', 'answer_yes'),
        CallbackButton::make('Нет', 'answer_no'),
    )
    ->row(
        LinkButton::make('Наш сайт', 'https://example.com'),
    )
    ->row(
        RequestContactButton::make('Поделиться контактом'),
        RequestGeoLocationButton::make('Отправить геолокацию'),
    );

OutgoingMessage::create('Выберите вариант:')
    ->to($userId)
    ->withKeyboard($keyboard)
    ->send();
```

---

Вебхуки
-------

[](#вебхуки)

### 1. Настройка маршрута

[](#1-настройка-маршрута)

Маршрут регистрируется автоматически. По умолчанию: `POST /max-bot/webhook`.

Изменить путь через `.env`:

```
MAX_BOT_WEBHOOK_PATH=my-bot/updates
```

### 2. Защита подписью (рекомендуется)

[](#2-защита-подписью-рекомендуется)

```
MAX_BOT_WEBHOOK_SECRET=ваш_секрет
```

Middleware `VerifyMaxBotSignature` проверяет HMAC-подпись каждого запроса и возвращает `403` при несовпадении.

### 3. Установить URL вебхука

[](#3-установить-url-вебхука)

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

### 4. Обработка событий

[](#4-обработка-событий)

Зарегистрируйте слушатели в `EventServiceProvider`:

```
use Dizvestnov\LaravelMaxBot\Events\MessageReceived;
use Dizvestnov\LaravelMaxBot\Events\CallbackReceived;
use Dizvestnov\LaravelMaxBot\Events\BotStarted;

protected $listen = [
    MessageReceived::class => [
        App\Listeners\HandleMessage::class,
    ],
    CallbackReceived::class => [
        App\Listeners\HandleCallback::class,
    ],
    BotStarted::class => [
        App\Listeners\WelcomeNewUser::class,
    ],
];
```

Пример слушателя:

```
namespace App\Listeners;

use Dizvestnov\LaravelMaxBot\Events\MessageReceived;
use Dizvestnov\LaravelMaxBot\Messages\OutgoingMessage;

class HandleMessage
{
    public function handle(MessageReceived $event): void
    {
        $text   = $event->getText();
        $userId = $event->getSenderId();

        OutgoingMessage::create("Вы написали: {$text}")
            ->to($userId)
            ->send();
    }
}
```

### 5. Доступные события

[](#5-доступные-события)

КлассКогда срабатывает`MessageReceived`Получено новое сообщение`MessageEdited`Сообщение отредактировано`MessageRemoved`Сообщение удалено`CallbackReceived`Нажата callback-кнопка`BotStarted`Пользователь запустил бота`BotAdded`Бот добавлен в чат`BotRemoved`Бот удалён из чата`UserAdded`Пользователь добавлен в чат`UserRemoved`Пользователь удалён из чата`ChatTitleChanged`Изменено название чатаМетоды, доступные во всех событиях (наследуются от `MaxBotEvent`):

```
$event->getUpdateType();  // тип обновления
$event->getChatId();      // ID чата (или null)
$event->getTimestamp();   // unix-timestamp
$event->update;           // исходный массив обновления
```

`MessageReceived` дополнительно:

```
$event->getText();       // текст сообщения
$event->getSenderId();   // ID отправителя
$event->getMessage();    // полный массив сообщения
```

### 6. Обработка через очередь

[](#6-обработка-через-очередь)

```
MAX_BOT_QUEUE_ENABLED=true
MAX_BOT_QUEUE_CONNECTION=redis
MAX_BOT_QUEUE_NAME=bot
```

---

Long Polling
------------

[](#long-polling)

Для локальной разработки или простых сценариев без публичного URL:

```
php artisan max-bot:poll
```

Команда получает обновления циклически через API и диспатчит те же события, что и вебхук.

---

Управление состоянием разговора
-------------------------------

[](#управление-состоянием-разговора)

`StateManager` хранит состояние и данные пользователя в кэше Laravel.

```
use Dizvestnov\LaravelMaxBot\Conversation\StateManager;

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

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

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

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

        if ($step === 'ask_email') {
            $data = $this->state->getData($userId);
            // $data['name'] и $event->getText() — готово
            $this->state->clearState($userId);
            OutgoingMessage::create('Регистрация завершена!')->to($userId)->send();
        }
    }
}
```

### Методы StateManager

[](#методы-statemanager)

```
$state->getState(int $userId): ?string
$state->setState(int $userId, string $state, int $ttl = 3600): void
$state->clearState(int $userId): void

$state->getData(int $userId): array
$state->setData(int $userId, array $data, int $ttl = 3600): void
$state->mergeData(int $userId, array $data): void
```

---

Artisan-команды
---------------

[](#artisan-команды)

КомандаОписание`max-bot:webhook:set {url}`Установить URL вебхука`max-bot:webhook:info`Показать текущий вебхук`max-bot:webhook:remove`Удалить вебхук`max-bot:poll`Запустить long polling---

Полный API-клиент
-----------------

[](#полный-api-клиент)

Все методы доступны через фасад `MaxBot::` или через DI `MaxBotClientInterface`:

```
use Dizvestnov\LaravelMaxBot\Contracts\MaxBotClientInterface;

class MyService
{
    public function __construct(private MaxBotClientInterface $bot) {}
}
```

**Бот**

```
MaxBot::getBotInfo();
MaxBot::editBotInfo(['name' => 'Новое имя']);
```

**Сообщения**

```
MaxBot::sendMessage([...]);
MaxBot::editMessage([...]);
MaxBot::deleteMessage($messageId);
MaxBot::getMessage($messageId);
MaxBot::getMessages(['chat_id' => $chatId]);
MaxBot::answerOnCallback(['callback_id' => $id, 'text' => 'OK']);
```

**Чаты**

```
MaxBot::getChats();
MaxBot::getChat($chatId);
MaxBot::editChat($chatId, ['title' => 'Новое название']);
MaxBot::deleteChat($chatId);
MaxBot::sendAction($chatId, 'typing');
MaxBot::getPinnedMessage($chatId);
MaxBot::pinMessage($chatId, ['message_id' => $messageId]);
MaxBot::unpinMessage($chatId);
```

**Участники**

```
MaxBot::getMembership($chatId);
MaxBot::leaveChat($chatId);
MaxBot::getAdmins($chatId);
MaxBot::addAdmins($chatId, [$userId]);
MaxBot::deleteAdmin($chatId, $userId);
MaxBot::getMembers($chatId);
MaxBot::addMembers($chatId, [$userId]);
MaxBot::deleteMember($chatId, $userId);
```

**Подписки и обновления**

```
MaxBot::getSubscriptions();
MaxBot::subscribe(['url' => 'https://...', 'secret' => '...']);
MaxBot::unsubscribe();
MaxBot::getUpdates(['limit' => 10]);
```

**Медиа**

```
MaxBot::getUploadUrl('image');
MaxBot::getVideoDetails($videoToken);
```

---

Тестирование
------------

[](#тестирование)

Мокайте `MaxBotClientInterface`:

```
use Dizvestnov\LaravelMaxBot\Contracts\MaxBotClientInterface;

public function test_bot_replies(): void
{
    $this->mock(MaxBotClientInterface::class, function ($mock) {
        $mock->shouldReceive('sendMessage')
            ->once()
            ->with(\Mockery::on(fn($p) => $p['text'] === 'Привет!'))
            ->andReturn(['message_id' => 'abc123']);
    });

    // вызвать логику, которая отправляет сообщение...
}
```

---

Статус проекта
--------------

[](#статус-проекта)

> **Пакет находится в активной разработке. Это первый публичный релиз.**
>
> API может изменяться до выхода стабильных версий 1.0.0 / 3.0.0. Используйте в production с осторожностью и закрепляйте конкретную версию в `composer.json`.

---

Сообщить об ошибке
------------------

[](#сообщить-об-ошибке)

1. **Поищите в существующих issues** — возможно, проблема уже известна: [github.com/dizvestnov/laravel-max-bot/issues](https://github.com/dizvestnov/laravel-max-bot/issues)
2. **Создайте новый issue**, указав:

    - версию пакета (`composer show dizvestnov/laravel-max-bot`)
    - версию PHP и Laravel
    - минимальный воспроизводимый пример кода
    - ожидаемое поведение и что происходит на самом деле
    - полный текст ошибки / стектрейс
3. **Для вопросов** используйте [Discussions](https://github.com/dizvestnov/laravel-max-bot/discussions), а не Issues.

Участие в разработке
--------------------

[](#участие-в-разработке)

1. Форкните репозиторий и создайте ветку от `main` (3.x) или `1.x`
2. Напишите или обновите тесты — покрытие обязательно
3. Убедитесь, что все проверки проходят локально: ```
    ./vendor/bin/phpunit          # тесты
    ./vendor/bin/pint             # стиль кода (3.x)
    ./vendor/bin/php-cs-fixer fix # стиль кода (1.x)
    ./vendor/bin/phpstan analyse  # статический анализ
    ```
4. Откройте Pull Request с описанием изменений

Ветка `2.x` намеренно пропущена — PR приветствуются.

---

Лицензия
--------

[](#лицензия)

[MIT](LICENSE)

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance81

Actively maintained with recent releases

Popularity9

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

7

Last Release

100d ago

Major Versions

v1.0.0 → v3.0.02026-04-14

1.x-dev → v3.0.12026-04-15

PHP version history (2 changes)v1.0.0PHP ^7.4|^8.0

v3.0.0PHP ^8.2

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/40119648?v=4)[Dmitriy](/maintainers/dizvestnov)[@dizvestnov](https://github.com/dizvestnov)

---

Top Contributors

[![dizvestnov](https://avatars.githubusercontent.com/u/40119648?v=4)](https://github.com/dizvestnov "dizvestnov (16 commits)")

---

Tags

apilaravelbotMessengermaxchatbot

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/dizvestnov-laravel-max-bot/health.svg)

```
[![Health](https://phpackages.com/badges/dizvestnov-laravel-max-bot/health.svg)](https://phpackages.com/packages/dizvestnov-laravel-max-bot)
```

###  Alternatives

[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M133](/packages/roots-acorn)[spatie/laravel-export

Create a static site bundle from a Laravel app

674146.0k6](/packages/spatie-laravel-export)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5022.6k](/packages/simplestats-io-laravel-client)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

255.2k](/packages/aedart-athenaeum)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

293.1k](/packages/eslazarev-wildberries-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)