README

Этот пакет предназначен для работы с Max API в полностью объектно-ориентированном формате. Все запросы, ответы и события сервера представлены в строго типизированном объектном виде, никаких array shapes (object-like arrays).

Весь задокументированный функционал реализован, включая возможность возобновления загрузки файлов.

Представление данных в виде объектов делает этот пакет предпочтительным для новичков: не нужно разбираться в документации и изучать структуру данных API Max — IDE сама подскажет доступные поля и методы.

Актуальность: 12 мая 2026 г.
Версия схемы API: 0.0.30

use MaxMessenger\Bot\MaxApiClient;

$apiClient = new MaxApiClient('your-access-token');

$apiClient->sendMessageToUser(12345678, 'Привет');

use MaxMessenger\Bot\MaxBot;
use MaxMessenger\Bot\MaxBot\Events\BotStartedEvent;
use MaxMessenger\Bot\MaxBot\Events\MessageCreatedEvent;

$bot = new MaxBot('your-access-token', 'your-secret');

$bot->onBotStarted(function (BotStartedEvent $event): void {
    $event->sendToChat(sprintf('Здравствуйте, %s!', $event->getUser()->getFirstName()));
});

$bot->onMessageCreated(function (MessageCreatedEvent $event): void {
    $message = $event->getMessage()->getText();
    // Обработка сообщения
    $event->reply('Ваше сообщение получено.', true);
});

$bot->handleFromGlobal();

Warning

По поводу ошибок в клиенте, пожалуйста обращайтесь ко мне напрямую:

• Max: Евгений
• Telegram: mj4444ru

Note

Вы можете заметить некоторые отличия реализации от официальной документации. На самом деле, официальная документация может содержать неточности или иметь дублирующиеся способы получения данных.

Некоторые недокументированные в официальном API функции могут быть отключены на стороне Max. Когда они писались и тестировались, они работали.

Если вы думаете, что этот пакет слишком сложный

1. Если Вам нужно просто отправить сообщение, то никакие пакеты Вам не нужны, просто прочитайте главу Отправка сообщений используя curl в разделе Отправка сообщений.
2. Если Вам нужно что-то ещё, прочитайте раздел Очень простой бот.

Основные особенности

• Это полностью объектно-ориентированный клиент без array shapes (object-like arrays).
• Для работы с клиентом не требуется изучение официального API.
• В большинстве случаев для понимания работы, Вам достаточно будет посмотреть примеры кода.
• Есть валидация данных в моделях запросов (можно отключить).
• Реализована загрузка файлов на сервера обоими поддерживаемыми способами.
• Имеются утилиты (скрипты) для тестирования и отладки обработки событий сервера.
• Весь функционал разбит на слои (бот, API Max клиент, HTTP клиент для API Max, Curl HTTP клиент), каждый слой может быть частично или полностью заменён Вашей реализацией (используются интерфейсы и многие внутренние методы объявлены как публичные).
• Код реализован с возможностью написания тестов для любой части Вашего кода.
• API Max клиент реализован на основе официальной документации API Max в формате yaml.
  • Объектная модель, имена моделей, имена параметров сохранены. Документирование откорректировано и дополнено.
  • Дополнительно добавлено множество методов, упрощающих работу с API.

Документация в коде

I believe that in-code documentation should be in English. However, due to a lack of resources to translate the documentation into English, the in-code documentation is presented in Russian.

Я считаю, что документация в публичном коде должна быть на английском языке. Однако из-за нехватки ресурсов для перевода документации на английский язык, документация в коде представлена на русском языке.

Установка

composer require max-messenger-bot/max-bot-api-php

Требования

• PHP 8.2+
• Расширение ext-mbstring

Зависимости

• mj4444/simple-http-client ^0.2 — HTTP-клиент для выполнения запросов

Примеры

Больше примеров смотрите в документации в разделе примеры.

Обработка событий сервера через Webhook (основной метод)

use MaxMessenger\Bot\MaxBot;
use MaxMessenger\Bot\MaxBot\Events\BotStartedEvent;
use MaxMessenger\Bot\MaxBot\Events\MessageCreatedEvent;

$bot = new MaxBot('your-access-token', 'your-secret');

// Добавление обработчика команды
$bot->getCommandHandler()
    ->onCommand('start', function (MessageCreatedEvent $event): bool {
        // Обработка команды /start
        return true;
    });

// Добавление обработчика присоединения нового пользователя
$bot->onBotStarted(function (BotStartedEvent $event): bool {
    // Обработка события
    return true;
});

// Добавление обработчика сообщений
$bot->onMessageCreated(function (MessageCreatedEvent $event): bool {
    // Обработка нового сообщения
    $event->reply('Ваше сообщение получено', true);
    return true;
});

$bot->handleFromGlobal();

Обработка событий сервера через Long Polling

use MaxMessenger\Bot\MaxBot;

$bot = new MaxBot('your-access-token', 'your-secret');

// Добавление обработчиков

// Запуск обработки событий с сервера
$marker = null;
while (true) {
    $marker = $bot->handleFromServer(marker: $marker);
    usleep(100000);
}

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

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

use MaxMessenger\Bot\MaxApiClient;

$apiClient = new MaxApiClient('your-access-token');

$apiClient->sendMessageToUser(12345678, 'Привет');

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

use MaxMessenger\Bot\MaxApiClient;
use MaxMessenger\Bot\Models\Requests\NewMessageBody;

$apiClient = new MaxApiClient('your-access-token');

$message = NewMessageBody::make('Сообщение с клавиатурой');
$message->addInlineKeyboard()->addLinkButton('Документация', 'https://dev.max.ru/docs-api');
$apiClient->sendMessageToUser(12345678, $message);

Отправка сообщения с файлом

use MaxMessenger\Bot\MaxApiClient;
use MaxMessenger\Bot\Models\Requests\NewMessageBody;

$apiClient = new MaxApiClient('your-access-token');

$message = NewMessageBody::new()
    ->addFileAttachment($fileToken);
$apiClient->sendMessageToUser(12345678, $message);

Загрузка файлов на сервера Max

Для загрузки файлов на сервера Max установите и используйте пакет max-messenger-bot/max-uploader-php.

composer require max-messenger-bot/max-uploader-php

Документация

• Начало работы
• Список документации