Max Messenger Bot API Client library for PHP

Caution

На мой взгляд Max Messenger является ни чем иным как малварью, созданной для слежки за гражданами РФ. Настоятельно не рекомендую использовать его на реальных устройствах, с настоящим номером телефона, и для личной переписки.
Обязательно к прочтению - Месседжер MAX следит за пользователями VPN

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

Если вы новичок, то можете прочитать официальную документацию, написанную разработчиками Max.

ℹ️ С полной документацией вы можете ознакомиться тут.

Получение токена

Откройте диалог с MasterBot, следуйте инструкциям и создайте нового бота. После создания бота MasterBot отправит вам токен.

Установка библиотеки

composer require bushlanov-dev/max-bot-api-client-php

Пользователи Laravel могут зарегистрировать сервис провайдер и фасад в config/app.php:

'providers' => [
    // ...
    BushlanovDev\MaxMessengerBot\Laravel\MaxBotServiceProvider::class,
],
// ...
'aliases' => [
    // ...
    'MaxBot' => BushlanovDev\MaxMessengerBot\Laravel\MaxBotFacade::class,
],

Использование

Note

С 19 июля 2026 основной домен api изменится с platform-api.max.ru на platform-api2.max.ru и начнет использовать чебурнетовский сертификат!
Вам необходимо либо установить сертификат, либо отключить его проверку, оба варианта описаны ниже.

Установка сертификата на примере ОС Ubuntu

# корневой сертификат
curl -k -O "https://gu-st.ru/content/Other/doc/russian_trusted_root_ca.cer"
# промежуточный сертификат
curl -k -O "https://gu-st.ru/content/Other/doc/russian_trusted_sub_ca.cer"

sudo cp russian_trusted_root_ca.cer /usr/local/share/ca-certificates/russian_trusted_root_ca.crt
sudo cp russian_trusted_sub_ca.cer  /usr/local/share/ca-certificates/russian_trusted_sub_ca.crt

sudo update-ca-certificates

Tip

Гибкая настройка Guzzle
Мах часто меняют домен API а теперь еще и сертификат.
Если вы не хотите или не можете установить сертификат на прямую в систему, можно собрать объект API с кастомным Guzzle клиентом и отключить проверку сертификата.
Во всех остальных случаях достаточно минимального $api = new Api('YOUR_BOT_API_TOKEN');

$guzzle = new \GuzzleHttp\Client([
    'timeout' => 10,
    'connect_timeout' => 5,
    'read_timeout' => 10,
    'headers' => ['User-Agent' => 'max-bot-api-client-php'],
    'verify' => false, // Отключить проверку либо путь до сертификата '/path/to/cert.pem'
]);

$httpFactory = new \GuzzleHttp\Psr7\HttpFactory();

$client = new \BushlanovDev\MaxMessengerBot\Client(
    accessToken: 'YOUR_BOT_API_TOKEN',
    httpClient: $guzzle,
    requestFactory: $httpFactory,
    streamFactory: $httpFactory,
    baseUrl: 'https://platform-api2.max.ru',
);

$api = new BushlanovDev\MaxMessengerBot\Api(
    client: $client,
    modelFactory: new BushlanovDev\MaxMessengerBot\ModelFactory(),
);

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

require __DIR__.'/vendor/autoload.php';

use BushlanovDev\MaxMessengerBot\Api;

$api = new Api('YOUR_BOT_API_TOKEN');

// Загрузка файла
$fileAttachmentRequest = $api->uploadAttachment(
    type: UploadType::File,
    filePath: __DIR__ . '/test.pdf',
);

$api->sendMessage(
    userId: 123,     // ID пользователя получателя сообщения
    chatId: 321,     // Или ID чата, в который нужно отправить сообщение
    text: 'Привет!', // Текст сообщения, вы можете использовать HTML или Markdown
    attachments: [
        $fileAttachmentRequest,
        new InlineKeyboardAttachmentRequest([
            [new CallbackButton('Нажми меня!', 'payload_button1')],
            [new LinkButton('Нажми меня!', 'https://example.com')],
        ]),
    ],
    format: MessageFormat::Markdown, // Формат сообщения (Markdown или HTML)
);

Отправка сообщения с использованием фасада Laravel

MaxBot::sendUserMessage(123456, 'Привет из Laravel!');

Создание универсального обработчика обновлений

$dispatcher = $api->getUpdateDispatcher();

$dispatcher->onMessageCreated(function (MessageCreatedUpdate $update, Api $api) {
    $api->sendMessage(
        userId: $update->message->recipient->userId,
        text: 'Привет!',
    );
});
// или
$dispatcher->addHandler(UpdateType::BotStarted, function (BotStartedUpdate $update, Api $api) {
    $api->sendMessage(
        chatId: $update->chatId,
        text: 'Я запущен!',
    );
});

Подписка на вэб хуки

$api->subscribe(
    url: 'https://example.com/webhook', // HTTPS URL на который будут приходить хуки
    secret: 'super_secret',             // Секретная фраза для проверки хуков
    updateTypes: [
        // Типы хуков которые вы хотите получать (либо ничего не указывать, чтобы получать все)
        UpdateType::BotStarted,
        UpdateType::MessageCreated,
    ],
);

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

$handler = $api->createWebhookHandler('super_secret'); // Обновления через вебхук
// ИЛИ
$handler = $api->createLongPollingHandler();           // Обновления через лонгполлинг

$handler->handle();

ℹ️ С полной документацией вы можете ознакомиться тут.

Реализованные методы

Bots

• GET /me (getBotInfo) - Получение информации о боте.
• PATCH /me (editBotInfo) - Редактирование информации о боте.

Chats

• GET /chats (getChats) - Получение списка всех чатов бота. (deprecated)
• GET /chats/{chatLink} (getChatByLink) - Получение информации о чате по ссылке.
• GET /chats/{chatId} (getChat) - Получение информации о чате по ID.
• PATCH /chats/{chatId} (editChat) - Редактирование информации о чате.
• DELETE /chats/{chatId} (deleteChat) - Удаление чата.
• POST /chats/{chatId}/actions (sendAction) - Отправка действия в чат (например, "печатает...").
• GET /chats/{chatId}/pin (getPinnedMessage) - Получение закрепленного сообщения.
• PUT /chats/{chatId}/pin (pinMessage) - Закрепление сообщения.
• DELETE /chats/{chatId}/pin (unpinMessage) - Открепление сообщения.
• GET /chats/{chatId}/members/me (getMembership) - Получение информации о членстве бота в чате.
• DELETE /chats/{chatId}/members/me (leaveChat) - Выход бота из чата.
• GET /chats/{chatId}/members/admins (getAdmins) - Получение администраторов чата.
• POST /chats/{chatId}/members/admins (addAdmins) - Назначение администраторов чата.
• DELETE /chats/{chatId}/members/admins/{userId} (deleteAdmin) - Снятие прав администратора.
• GET /chats/{chatId}/members (getMembers) - Получение участников чата.
• POST /chats/{chatId}/members (addMembers) - Добавление участников в чат.
• DELETE /chats/{chatId}/members (deleteMember) - Удаление участника из чата.

Subscriptions

• GET /subscriptions (getSubscriptions) - Получение списка Webhook-подписок.
• POST /subscriptions (subscribe) - Создание Webhook-подписки.
• DELETE /subscriptions (unsubscribe) - Удаление Webhook-подписки.
• GET /updates (getUpdates) - Получение обновлений через Long-Polling.

Upload

• POST /uploads (getUploadUrl) - Получение URL для загрузки файла.

Messages

• GET /messages (getMessages) - Получение списка сообщений из чата.
• POST /messages (sendMessage) - Отправка сообщения.
• PUT /messages (editMessage) - Редактирование сообщения.
• DELETE /messages (deleteMessage) - Удаление сообщения.
• GET /messages/{messageId} (getMessageById) - Получение сообщения по ID.
• GET /videos/{videoToken} (getVideoAttachmentDetails) - Получение детальной информации о видео.
• POST /answers (answerOnCallback) - Ответ на нажатие callback-кнопки.

Лицензия

Данная библиотека распространяется под лицензией MIT - подробности см. в файле LICENSE.