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

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: BushlanovDev\MaxMessengerBot\Api::API_BASE_URL,
);

$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/commands (editBotCommands) - Редактирование команд бота.
• PATCH /me (editBotInfo) - Редактирование информации о боте. (deprecated)

Chats

• GET /chats (getChats) - Получение списка всех чатов бота. (deprecated)
• GET /chats/{chatLink} (getChatByLink) - Получение информации о чате по ссылке. (deprecated)
• GET /chats/{chatId} (getChat) - Получение информации о чате по ID.
• PATCH /chats/{chatId} (editChat) - Редактирование информации о чате.
• DELETE /chats/{chatId} (deleteChat) - Удаление чата. (deprecated)
• 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) - Добавление участников в чат. (deprecated, удаляется 30.09.2026)
• 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-кнопки.

Comments

• GET /messages/{messageId}/comments (getComments) - Получение комментариев к посту.
• GET /messages/{messageId}/comments/{commentId} (getCommentById) - Получение комментария по ID.
• POST /messages/{messageId}/comments (sendComment) - Отправка комментария.
• PUT /messages/{messageId}/comments (editComment) - Редактирование комментария.
• DELETE /messages/{messageId}/comments (deleteComment) - Удаление комментария.

Лицензия

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