max-api-php/client

PHP SDK for the MAX Bot API.

dev-main 2026-04-04 20:52 UTC

Requires

• php: ^8.2

Suggests

• ext-json: Required to encode requests and decode API responses.

MIT

• php
• api
• bot
• Messenger
• max

README

PHP SDK для MAX Bot API в стиле telegram-bot/api: один entry point, отдельные API-модули, payload builder'ы, typed wrapper'ы, webhook parsing и long polling.

Состояние

SDK выровнен по публичной max-bot-api-schema и покрывает все операции, которые сейчас объявлены в paths.

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

• bots
• chats
• messages
• subscriptions
• uploads

Реализованные слои:

• API-модули в MaxApi\Api\*
• payload builder'ы в MaxApi\Input\*
• typed wrapper'ы в MaxApi\Type\*
• разбор webhook через MaxApi\Webhook\WebhookHandler
• HTTP transport без внешних зависимостей на основе PHP streams

Требования

• PHP 8.2+
• Composer

Установка

composer require max-api-php/client

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

<?php

declare(strict_types=1);

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

use MaxApi\BotApi;
use MaxApi\Input\NewMessageBody;
use MaxApi\Type\BotCommand;

$api = new BotApi($_ENV['MAX_BOT_TOKEN']);

$me = $api->bots->me();

$api->bots->setMyCommands([
    BotCommand::make('start', 'Запустить бота'),
]);

$message = $api->messages->sendMessage(
    NewMessageBody::make('Привет из PHP')->format('markdown'),
    chatId: 123456789
);

Long Polling

<?php

declare(strict_types=1);

use MaxApi\BotApi;

$api = new BotApi($_ENV['MAX_BOT_TOKEN']);
$marker = null;

while (true) {
    $updates = $api->subscriptions->getUpdates(
        limit: 100,
        timeout: 25,
        marker: $marker
    );

    if ($updates->has('marker')) {
        $marker = $updates->marker;
    }

    foreach ($updates->items() as $update) {
        // обработка update
    }
}

В testbot/run.php лежит рабочий CLI-пример polling-бота, который:

• запрашивает токен при старте
• регистрирует команду /start
• удаляет активные webhook subscriptions
• отвечает сообщением с chat_id и user_id

Webhook

<?php

declare(strict_types=1);

use MaxApi\BotApi;
use MaxApi\Input\NewMessageBody;

$api = new BotApi($_ENV['MAX_BOT_TOKEN']);
$handler = $api->webhookHandler($_ENV['MAX_BOT_SECRET']);
$update = $handler->handle(file_get_contents('php://input') ?: '', $_SERVER);

if ($update->update_type === 'message_created') {
    $chatId = $update->message['recipient']['chat_id'] ?? null;

    if ($chatId !== null) {
        $api->messages->sendMessage(
            NewMessageBody::make('Webhook получен'),
            chatId: (int) $chatId
        );
    }
}

Что покрыто

• GET /me, PATCH /me
• команды бота через patch данных бота
• чаты, участники, админы, actions, pinning
• сообщения, callbacks, видео-метаданные
• webhook subscriptions и long polling updates
• получение upload URL и helper для multipart upload

Что уже проверено на практике

Следующие сценарии уже были прогнаны на реальном MAX-боте:

• GET /me
• регистрация команд
• long polling через GET /updates
• ответ на /start с возвратом chat_id и user_id

Нюанс, который уже подтвердился:

• GET /updates может зависеть от географии сети или egress route; в одном окружении polling не работал, а с московского IP работал штатно

Структура пакета

src/
  Api/
  Contract/
  Exception/
  Http/
  Input/
  Support/
  Type/
  Webhook/
testbot/

Заметки

• Это низкоуровневый SDK-слой. Более высокий bot framework лучше строить поверх него отдельным пакетом.
• Часть вложенных объектов MAX пока остается обычными массивами внутри wrapper-типов. Публичный API уже рабочий, но детализацию DTO еще можно улучшать.
• Следующий практический шаг: расширять integration coverage и подтягивать DTO к схеме еще точнее.