PHP-пакеты для Max Bot API

Объектно-ориентированные библиотеки для разработки ботов мессенджера Max на PHP. Пакеты реализуют полный интерфейс к Max Bot API без array shapes — все запросы, ответы и события представлены строго типизированными объектами. Представление данных в виде объектов делает пакеты предпочтительными для новичков: не нужно разбираться в документации и изучать структуру данных API Max — IDE сама подскажет доступные поля и методы.

Требования

max-bot-api-php

PHP SDK for the Max Messenger Bot API — Клиент для работы с Max Bot API без привязки к конкретному фреймворку. Подходит для любого PHP-проекта — от простых скриптов до крупных приложений.

Установка

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

Возможности

• Полностью объектно-ориентированный API-клиент без array shapes
• Для начала работы достаточно примеров кода — знание официального API не требуется
• Валидация данных в моделях запросов (можно отключить)
• Обработка Webhook и Long Polling
• Обработчики событий: onMessageCreated, onBotStarted и другие
• Обработчик команд через getCommandHandler()->onCommand()
• Загрузка файлов обоими методами, включая возобновляемую загрузку
• Слоистая архитектура: бот, API-клиент, HTTP-клиент — каждый уровень заменяем
• Модели и имена параметров соответствуют официальной документации Max Bot API
• Код структурирован для удобного написания тестов
• Утилиты для тестирования и отладки обработки обновлений

Обработка обновлений через Webhook

Рекомендуемый способ. Создайте файл, доступный по публичному URL, и укажите его как 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 {
        $event->reply('Добро пожаловать!', true);
        return true;
    });

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

$bot->onMessageCreated(function (MessageCreatedEvent $event): bool {
    $event->reply('Ваше сообщение получено.', true);
    return true;
});

$bot->handleFromGlobal();

Обработка обновлений через Long Polling

Альтернативный метод — получение обновлений без настройки Webhook:

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, 'Привет!');

Сообщение с кнопкой

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

$apiClient->sendMessageToUser(12345678, $message);

Сообщение с файлом

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

max-uploader-php

Пакет для загрузки файлов на серверы Max API в полностью объектно-ориентированном формате. Поддерживает отслеживание прогресса, логирование и валидацию данных. Зависит от max-bot-api-php и используется совместно с ним.

Установка

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

Возможности

• Загрузка файлов двумя поддерживаемыми методами
• Отслеживание прогресса загрузки
• Логирование операций
• Полностью объектно-ориентированная архитектура
• Валидация входных и выходных данных
• Слоистая архитектура с возможностью замены любого уровня

Методы загрузки

max-bot-api-laravel

Пакет для интеграции Max Bot API с приложениями на Laravel. Строится поверх max-bot-api-php и предоставляет привычные для Laravel-разработчиков инструменты: service provider, фасад MaxApi, конфигурационный файл, маршруты и миграции базы данных.

Установка

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

Service provider и фасад регистрируются автоматически через Laravel Package Discovery.

Возможности

• Service provider MaxServiceProvider с автоматической регистрацией
• Фасад MaxApi для удобного доступа к API-клиенту из любого места приложения
• Публикуемый конфигурационный файл с токеном доступа и секретом Webhook
• Готовые маршруты для обработки входящих Webhook-запросов
• Миграции базы данных
• Поддержка логирования через стандартный Laravel-логгер
• Полная совместимость с экосистемой max-bot-api-php

Зависимости

Частые вопросы

Что такое Max Bot API?

Max Bot API — программный интерфейс мессенджера Max, позволяющий создавать чат-ботов и автоматизировать взаимодействие с пользователями. Через API можно отправлять и получать сообщения, работать с вложениями, создавать интерактивные клавиатуры и подписываться на события.

Что такое PHP SDK для Max Messenger?

Пакет max-bot-api-php — это PHP SDK для Max Messenger, реализующий полный интерфейс Max Bot API в объектно-ориентированном формате. Он устроен так, что для начала работы достаточно примеров кода — изучение официальной документации API не обязательно.

Можно ли использовать пакет с любым PHP-фреймворком?

Да. max-bot-api-php не зависит от конкретного фреймворка и подходит для любого PHP-проекта — от простых скриптов до крупных приложений.

Как создать бота в Max мессенджере на PHP?

Установите пакет через Composer, получите токен доступа в настройках бота Max, создайте экземпляр MaxBot с токеном и зарегистрируйте обработчики событий. Подробнее — в разделе max-bot-api-php.

Как подключить Max Bot API к PHP-проекту?

Выполните установку через Composer: composer require max-messenger-bot/max-bot-api-php. Затем создайте экземпляр MaxBot, передав токен доступа и секрет для проверки Webhook-подписи.

Как настроить Webhook для бота Max?

Создайте публично доступный PHP-файл, добавьте в него обработчики событий и вызовите $bot->handleFromGlobal(). Укажите URL этого файла как Webhook-адрес в настройках бота в мессенджере Max.

Чем отличается Webhook от Long Polling?

Webhook — рекомендуемый метод: сервер Max сам отправляет обновления на ваш URL при каждом событии. Long Polling — альтернатива для окружений без публичного URL: бот периодически запрашивает обновления с серверов Max самостоятельно.

Как отправить сообщение через Max API на PHP?

Создайте экземпляр MaxApiClient с токеном доступа и вызовите метод sendMessageToUser(). Подробнее — в разделе Отправка сообщений.

Как добавить инлайн-клавиатуру в сообщение бота Max?

Создайте объект NewMessageBody, вызовите addInlineKeyboard() и добавьте кнопки методами addLinkButton() или другими доступными методами. Пример — в разделе Отправка сообщений.

Как обрабатывать команды бота Max на PHP?

Используйте $bot->getCommandHandler()->onCommand('название', callback). Обработчик будет вызван, когда пользователь отправит команду с указанным именем.

Как загрузить файл через Max API на PHP?

Установите пакет max-uploader-php командой composer require max-messenger-bot/max-uploader-php. Он предоставляет два класса: MaxUploader для возобновляемой загрузки (рекомендуется) и MaxSimpleUploader для multipart-загрузки.

Что такое возобновляемая загрузка файлов?

Resumable upload — метод загрузки, при котором прерванная передача файла может быть продолжена с места остановки, а не начата заново. Класс MaxUploader реализует этот подход для серверов Max API, что особенно важно при загрузке больших файлов.

Как отправить сообщение в мессенджер Max в Laravel?

Установите пакет max-bot-api-laravel, который предоставляет интеграцию с Laravel:

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

После установки вы можете использовать MaxApiClient через dependency injection или напрямую — аналогично любому другому PHP-проекту. Для отправки сообщения пользователю используйте метод sendMessageToUser():

use MaxMessenger\Bot\MaxApiClient;

$apiClient = app(MaxApiClient::class);
$apiClient->sendMessageToUser(12345678, 'Привет из Laravel!');

Пакет max-bot-api-laravel регистрирует service provider автоматически и публикует конфигурационный файл с токеном доступа и секретом Webhook. Подробнее — в репозитории на GitHub.

Как проверить хэш (hash) информации о пользователе в формате VCF (vcf_info)?

Используйте метод validateContactAttachmentHash($payload) класса MaxApiClient. Он проверяет соответствие хеша и значения vcfInfo, позволяя убедиться, что пользователь поделился номером телефона, привязанным к его аккаунту в Max.

Метод принимает объект ContactAttachmentPayload и возвращает bool: true — если хеш совпадает, false — если нет. После успешной проверки номер телефона можно получить через $payload->getPhones().

Для удобства можно также использовать MessageCreatedEvent::isSelfContact() — он выполняет ту же проверку непосредственно внутри обработчика события входящего сообщения.

О Max Messenger и Bot API

Max — российский мессенджер с Bot API для создания чат-ботов и интеграций. Max Bot API позволяет получать и отправлять сообщения, работать с вложениями, создавать интерактивные клавиатуры, подписываться на события и автоматизировать взаимодействие с пользователями.

Пакеты max-bot-api-php и max-uploader-php — PHP-библиотеки с открытым исходным кодом для разработки ботов Max Messenger. Они избавляют разработчика от работы с сырыми HTTP-запросами и массивами: все сущности API представлены строго типизированными объектами с валидацией данных. max-uploader-php дополняет основной клиент расширенными возможностями загрузки файлов, включая возобновляемую загрузку и отслеживание прогресса.

Библиотеки подходят для создания чат-ботов поддержки, систем автоматических уведомлений, интерактивных меню, ботов с поддержкой медиафайлов, интеграций с CRM и внешними сервисами, а также полноценных приложений на платформе Max Messenger.

Полезные ссылки

• max-bot-api-php — GitHub
• max-uploader-php — GitHub
• max-bot-api-laravel — GitHub
• Официальная документация для разработчиков Max
• Справочник Max Bot API
• Создание чат-бота в Max Messenger