PHPackages                             blacky0892/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. blacky0892/laravel-max-bot

ActiveLibrary[API Development](/categories/api)

blacky0892/laravel-max-bot
==========================

Laravel package for MAX Bot API

v0.1.0(1w ago)02↓100%MITPHPPHP ^8.2

Since Mar 16Pushed 1w agoCompare

[ Source](https://github.com/Blacky0892/laravel-max-bot)[ Packagist](https://packagist.org/packages/blacky0892/laravel-max-bot)[ RSS](/packages/blacky0892-laravel-max-bot/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (6)Versions (2)Used By (0)

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

[](#laravel-max-bot)

Laravel-пакет для удобной работы с **MAX Bot API** в приложениях на Laravel.

Пакет предоставляет:

- HTTP-клиент для запросов к MAX Bot API;
- удобную обёртку для отправки сообщений пользователям и в чаты;
- сервис для управления webhook-подписками;
- сервис для ответа на callback-события;
- встроенный webhook-роут для приёма входящих обновлений;
- artisan-команды для генерации handler-класса и регистрации webhook;
- базовую интеграцию с контейнером Laravel через Service Provider и Facade.

> Пакет находится в активной разработке. API может расширяться в следующих версиях.

---

Требования
----------

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

- PHP 8.2+
- Laravel 10 / 11 / 12

---

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

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

Установите пакет через Composer:

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

Опубликуйте конфигурационный файл:

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

---

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

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

Добавьте переменные в `.env`:

```
MAX_BOT_TOKEN=your_token
MAX_BASE_URL=https://platform-api.max.ru
MAX_WEBHOOK_SECRET=super-secret
MAX_ROUTE_ENABLED=true
MAX_ROUTE_PATH=/max/webhook
MAX_WEBHOOK_HANDLER=App\Services\Max\MaxWebhookHandler
```

---

Конфигурация
------------

[](#конфигурация)

После публикации будет создан файл `config/max.php`.

Пример:

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

    'base_url' => env('MAX_BASE_URL', 'https://platform-api.max.ru'),

    'timeout' => (int) env('MAX_TIMEOUT', 30),

    'connect_timeout' => (int) env('MAX_CONNECT_TIMEOUT', 10),

    'retry_times' => (int) env('MAX_RETRY_TIMES', 0),

    'retry_sleep' => (int) env('MAX_RETRY_SLEEP', 200),

    'webhook_secret' => env('MAX_WEBHOOK_SECRET'),

    'route' => [
        'enabled' => (bool) env('MAX_ROUTE_ENABLED', true),
        'path' => env('MAX_ROUTE_PATH', '/max/webhook'),
        'middleware' => ['api'],
    ],

    'webhook' => [
        'handler' => env('MAX_WEBHOOK_HANDLER', 'App\\Services\\Max\\MaxWebhookHandler'),
    ],
];
```

### Описание параметров

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

- `token` — токен вашего бота MAX.
- `base_url` — базовый URL API.
- `timeout` — таймаут HTTP-запросов.
- `connect_timeout` — таймаут соединения.
- `retry_times` — количество повторных попыток при ошибках.
- `retry_sleep` — задержка между повторами в миллисекундах.
- `webhook_secret` — секрет для проверки входящих webhook-запросов.
- `route.enabled` — включить автоматическую регистрацию webhook-роута.
- `route.path` — путь для webhook.
- `webhook.handler` — класс обработчика входящих обновлений.

---

Быстрый старт
-------------

[](#быстрый-старт)

### Обработка входящих обновлений

[](#обработка-входящих-обновлений)

Чтобы обрабатывать входящие webhook-запросы, создайте класс-обработчик, реализующий интерфейс `HandlesMaxUpdates`.

И укажите этот класс в `.env`:

```
MAX_WEBHOOK_HANDLER=App\Services\Max\MaxWebhookHandler
```

После изменения конфигурации очистите кэш:

```
php artisan config:clear
```

Можно воспользоваться командой для генерации демо-версии обработчика

```
php artisan make:max-webhook-handler
```

Это создаст файл `app/Services/Max/MaxWebhookHandler.php`.

Можно указать своё имя или путь:

```
php artisan make:max-webhook-handler Services/Bots/MainMaxHandler
```

### Регистрация webhook одной командой

[](#регистрация-webhook-одной-командой)

Когда приложение уже доступно по HTTPS и роут webhook включён, можно зарегистрировать подписку прямо из artisan:

```
php artisan max:webhook-register
```

По умолчанию команда:

- берёт `APP_URL` из `.env`;
- добавляет к нему `MAX_ROUTE_PATH`;
- использует `MAX_WEBHOOK_SECRET`;
- подписывает на `message_created,message_callback,bot_started`.

Можно передать свои параметры:

```
php artisan max:webhook-register \
  --url="https://example.com/max/webhook" \
  --types="message_created,message_callback,bot_started" \
  --secret="super-secret" \
  --version=1
```

Если нужно сначала посмотреть, что будет отправлено, а не выполнять запрос:

```
php artisan max:webhook-register --dry-run
```

### Получение информации о боте

[](#получение-информации-о-боте)

```
use Blacky0892\Max\Facades\Max;

$me = Max::client()->getMe();
```

### Отправка сообщения пользователю

[](#отправка-сообщения-пользователю)

```
use Blacky0892\Max\Facades\Max;

Max::client()->sendMessageToUser(
    userId: 123456,
    text: 'Привет из Laravel-пакета!',
    format: 'markdown'
);
```

### Отправка сообщения в чат

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

```
use Blacky0892\Max\Facades\Max;

Max::client()->sendMessageToChat(
    chatId: 987654,
    text: 'Сообщение в чат',
    format: 'html'
);
```

### Редактирование сообщения

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

```
Max::client()->editMessage(
    messageId: 1001,
    text: 'Обновлённый текст',
    format: 'markdown'
);
```

### Удаление сообщения

[](#удаление-сообщения)

```
Max::client()->deleteMessage(1001);
```

### Получение сообщений

[](#получение-сообщений)

```
$messages = Max::client()->getMessages(
    chatId: 987654,
    count: 20
);
```

---

Работа с вложениями
-------------------

[](#работа-с-вложениями)

### Загрузка файла по пути

[](#загрузка-файла-по-пути)

```
$upload = Max::client()->uploadFromPath(
    path: storage_path('app/public/file.pdf'),
    type: 'file'
);
```

### Загрузка файла из UploadedFile

[](#загрузка-файла-из-uploadedfile)

```
$upload = Max::client()->uploadFromUploadedFile(
    file: $request->file('document'),
    type: 'file'
);
```

### Отправка видео в чат

[](#отправка-видео-в-чат)

```
$upload = Max::client()->uploadFromPath(
    path: storage_path('app/public/video.mp4'),
    type: 'video'
);

Max::client()->sendVideoToChat(
    chatId: 987654,
    videoToken: $upload['token'],
    caption: 'Видео готово'
);
```

> Сейчас в пакете есть готовый метод `sendVideoToChat()`. Поддержку остальных типов вложений можно добавить аналогичным образом.

---

Работа с webhook-подписками
---------------------------

[](#работа-с-webhook-подписками)

### Получить список подписок

[](#получить-список-подписок)

```
$subscriptions = Max::subscriptions()->all();
```

### Создать подписку

[](#создать-подписку)

```
use Blacky0892\Max\Facades\Max;

Max::subscriptions()->create(
    url: 'https://example.com/max/webhook',
    updateTypes: ['message_created', 'message_callback'],
    secret: config('max.webhook_secret'),
    version: 1,
);
```

### Удалить подписку

[](#удалить-подписку)

```
Max::subscriptions()->delete('https://example.com/max/webhook');
```

---

Callback-события
----------------

[](#callback-события)

Если пользователь нажал на кнопку и MAX прислал callback, на него можно ответить так:

```
use Blacky0892\Max\Facades\Max;

Max::callbacks()->answer(
    callbackId: 'callback-id',
    notification: 'Действие выполнено'
);
```

Также пакет умеет извлекать `callback_id` из update-массива:

```
$callbackId = Max::callbacks()->callbackIdFromUpdate($update);
```

---

Встроенный webhook-роут
-----------------------

[](#встроенный-webhook-роут)

Если `MAX_ROUTE_ENABLED=true`, пакет автоматически регистрирует POST-роут:

```
/max/webhook

```

Путь можно изменить через `MAX_ROUTE_PATH`.

### Проверка секрета

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

Если задан `MAX_WEBHOOK_SECRET`, пакет проверяет заголовок:

```
X-Max-Bot-Api-Secret

```

Если секрет не совпадает, запрос будет отклонён с HTTP 403.

---

Объект Update
-------------

[](#объект-update)

Пакет содержит вспомогательный объект `Blacky0892\Max\Support\Update`, который упрощает работу с входящими payload.

### Основные методы

[](#основные-методы)

```
$update->raw();
$update->type();
$update->timestamp();
$update->chatId();
$update->userId();
$update->text();
$update->callbackId();
$update->messageId();
$update->get('message.body.text');
$update->isMessageCreated();
$update->isMessageCallback();
```

---

Пример сценария запуска webhook
-------------------------------

[](#пример-сценария-запуска-webhook)

1. Установить пакет.
2. Настроить `.env`.
3. Опубликовать конфиг.
4. Создать handler-класс.
5. Убедиться, что роут доступен по HTTPS.
6. Выполнить `php artisan max:webhook-register`.
7. Начать принимать события.

---

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

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

MIT

---

Автор
-----

[](#автор)

Blacky0892

---

Ссылки
------

[](#ссылки)

- [MAX Messenger](https://max.ru/)
- [MAX Bot API Documentation](https://platform-api.max.ru/docs/)

###  Health Score

37

—

LowBetter than 84% of packages

Maintenance98

Actively maintained with recent releases

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity35

Early-stage or recently created project

 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

Unknown

Total

1

Last Release

8d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/6ccac37d5137af65124910073fc8a8d11ae7a708b08aa59e475bc69e1dd94904?d=identicon)[Blacky0892](/maintainers/Blacky0892)

---

Top Contributors

[![Blacky0892](https://avatars.githubusercontent.com/u/10906029?v=4)](https://github.com/Blacky0892 "Blacky0892 (2 commits)")

---

Tags

apilaravelbotMessengermax

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

PHPackages © 2026

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