mirror of
https://github.com/BushlanovDev/max-bot-api-client-php.git
synced 2026-10-07 20:39:34 +00:00
Timofey
96dea75530
Methods (per the API changelog and schema 0.0.33):
- getChats(): GET /chats is not supported since June 2026
- getChatByLink(), deleteChat(): no longer documented, absent from
the schema
- addMembers(): POST /chats/{chatId}/members is limited since
9 September 2026 and removed on 30 September 2026
Models and enums absent from schema 0.0.33: the chat inline button,
reply buttons and ReplyButtonType, Intent, MessageChatCreatedUpdate
and its handlers, Chat::$chatMessageId.
Only @deprecated tags and docs; nothing is removed, so existing code
keeps working until a major release. README coverage map updated.
239 lines
15 KiB
Markdown
239 lines
15 KiB
Markdown
# Max Messenger Bot API Client library for PHP
|
||
|
||
[](https://github.com/BushlanovDev/max-bot-api-client-php/actions)
|
||
[](https://github.com/BushlanovDev/max-bot-api-client-php/actions)
|
||
[](https://packagist.org/packages/bushlanov-dev/max-bot-api-client-php)
|
||
[](https://github.com/BushlanovDev/max-bot-api-client-php)
|
||
[](https://github.com/BushlanovDev/max-bot-api-client-php)
|
||
[](LICENSE)
|
||
|
||
> [!CAUTION]
|
||
> На мой взгляд `Max Messenger` является ни чем иным как малварью, созданной для слежки за гражданами РФ. Настоятельно
|
||
> не рекомендую использовать его на реальных устройствах, с настоящим номером телефона, и для личной переписки.
|
||
> Обязательно к прочтению - [Месседжер MAX следит за пользователями VPN](https://habr.com/ru/articles/1006666/)
|
||
|
||
## Быстрый старт
|
||
|
||
> Если вы новичок, то можете прочитать [официальную документацию](https://dev.max.ru/), написанную разработчиками Max.
|
||
|
||
> ℹ️ С полной документацией [вы можете ознакомиться тут](./docs/README.md).
|
||
|
||
### Получение токена
|
||
|
||
Откройте диалог с [MasterBot](https://max.ru/MasterBot), следуйте инструкциям и создайте нового бота. После создания
|
||
бота MasterBot отправит вам токен.
|
||
|
||
### Установка библиотеки
|
||
|
||
```bash
|
||
composer require bushlanov-dev/max-bot-api-client-php
|
||
```
|
||
|
||
Пользователи Laravel могут зарегистрировать сервис провайдер и фасад в `config/app.php`:
|
||
|
||
```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
|
||
|
||
```bash
|
||
# корневой сертификат
|
||
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');
|
||
|
||
```php
|
||
$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(),
|
||
);
|
||
```
|
||
|
||
Отправка сообщения с клавиатурой
|
||
|
||
```php
|
||
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
|
||
|
||
```php
|
||
MaxBot::sendUserMessage(123456, 'Привет из Laravel!');
|
||
```
|
||
|
||
Создание универсального обработчика обновлений
|
||
|
||
```php
|
||
$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: 'Я запущен!',
|
||
);
|
||
});
|
||
```
|
||
|
||
Подписка на вэб хуки
|
||
|
||
```php
|
||
$api->subscribe(
|
||
url: 'https://example.com/webhook', // HTTPS URL на который будут приходить хуки
|
||
secret: 'super_secret', // Секретная фраза для проверки хуков
|
||
updateTypes: [
|
||
// Типы хуков которые вы хотите получать (либо ничего не указывать, чтобы получать все)
|
||
UpdateType::BotStarted,
|
||
UpdateType::MessageCreated,
|
||
],
|
||
);
|
||
```
|
||
|
||
Обработка обновлений
|
||
|
||
```php
|
||
$handler = $api->createWebhookHandler('super_secret'); // Обновления через вебхук
|
||
// ИЛИ
|
||
$handler = $api->createLongPollingHandler(); // Обновления через лонгполлинг
|
||
|
||
$handler->handle();
|
||
```
|
||
|
||
> ℹ️ С полной документацией [вы можете ознакомиться тут](./docs/README.md).
|
||
|
||
## Реализованные методы
|
||
|
||
#### Bots
|
||
|
||
- [x] `GET /me` (`getBotInfo`) - [*Получение информации о боте.*](./docs/README.md#Получение-информации-о-боте)
|
||
- [x] `PATCH /me/commands` (`editBotCommands`) - [*Редактирование команд бота.*](./docs/README.md#Редактирование-команд-бота)
|
||
- [x] ~~`PATCH /me` (`editBotInfo`) - [*Редактирование информации о боте.*](./docs/README.md#Редактирование-информации-о-боте-deprecated)~~ (deprecated)
|
||
|
||
#### Chats
|
||
|
||
- [x] ~~`GET /chats` (`getChats`) - [*Получение списка всех чатов бота.*](./docs/README.md#Получение-списка-всех-чатов-бота-deprecated)~~ (deprecated)
|
||
- [x] ~~`GET /chats/{chatLink}` (`getChatByLink`) - [*Получение информации о чате по ссылке.*](./docs/README.md#Получение-информации-о-чате-по-ссылке-deprecated)~~ (deprecated)
|
||
- [x] `GET /chats/{chatId}` (`getChat`) - [*Получение информации о чате по ID.*](./docs/README.md#Получение-информации-о-чате-по-ID)
|
||
- [x] `PATCH /chats/{chatId}` (`editChat`) - [*Редактирование информации о чате.*](./docs/README.md#Редактирование-информации-о-чате)
|
||
- [x] ~~`DELETE /chats/{chatId}` (`deleteChat`) - [*Удаление чата.*](./docs/README.md#Удаление-чата-deprecated)~~ (deprecated)
|
||
- [x] `POST /chats/{chatId}/actions` (`sendAction`) - [*Отправка действия в чат (например, "печатает...").*](./docs/README.md#Отправка-действия-в-чат)
|
||
- [x] `GET /chats/{chatId}/pin` (`getPinnedMessage`) - [*Получение закрепленного сообщения.*](./docs/README.md#Получение-закрепленного-сообщения)
|
||
- [x] `PUT /chats/{chatId}/pin` (`pinMessage`) - [*Закрепление сообщения.*](./docs/README.md#Закрепление-сообщения)
|
||
- [x] `DELETE /chats/{chatId}/pin` (`unpinMessage`) - [*Открепление сообщения.*](./docs/README.md#Открепление-сообщения)
|
||
- [x] `GET /chats/{chatId}/members/me` (`getMembership`) - [*Получение информации о членстве бота в чате.*](./docs/README.md#Получение-информации-о-членстве-бота-в-чате)
|
||
- [x] `DELETE /chats/{chatId}/members/me` (`leaveChat`) - [*Выход бота из чата.*](./docs/README.md#Выход-бота-из-чата)
|
||
- [x] `GET /chats/{chatId}/members/admins` (`getAdmins`) - [*Получение администраторов чата.*](./docs/README.md#Получение-администраторов-чата)
|
||
- [x] `POST /chats/{chatId}/members/admins` (`addAdmins`) - [*Назначение администраторов чата.*](./docs/README.md#Назначение-администраторов-чата)
|
||
- [x] `DELETE /chats/{chatId}/members/admins/{userId}` (`deleteAdmin`) - [*Снятие прав администратора.*](./docs/README.md#Снятие-прав-администратора)
|
||
- [x] `GET /chats/{chatId}/members` (`getMembers`) - [*Получение участников чата.*](./docs/README.md#Получение-участников-чата)
|
||
- [x] ~~`POST /chats/{chatId}/members` (`addMembers`) - [*Добавление участников в чат.*](./docs/README.md#Добавление-участников-в-чат-deprecated)~~ (deprecated, удаляется 30.09.2026)
|
||
- [x] `DELETE /chats/{chatId}/members` (`deleteMember`) - [*Удаление участника из чата.*](./docs/README.md#Удаление-участника-из-чата)
|
||
|
||
#### Subscriptions
|
||
|
||
- [x] `GET /subscriptions` (`getSubscriptions`) - [*Получение списка Webhook-подписок.*](./docs/README.md#Получение-списка-Webhook-подписок)
|
||
- [x] `POST /subscriptions` (`subscribe`) - [*Создание Webhook-подписки.*](./docs/README.md#Создание-Webhook-подписки)
|
||
- [x] `DELETE /subscriptions` (`unsubscribe`) - [*Удаление Webhook-подписки.*](./docs/README.md#Удаление-Webhook-подписки)
|
||
- [x] `GET /updates` (`getUpdates`) - [*Получение обновлений через Long-Polling.*](./docs/README.md#Получение-обновлений-через-Long-Polling)
|
||
|
||
#### Upload
|
||
|
||
- [x] `POST /uploads` (`getUploadUrl`) - [*Получение URL для загрузки файла.*](./docs/README.md#Получение-URL-для-загрузки-файла)
|
||
|
||
#### Messages
|
||
|
||
- [x] `GET /messages` (`getMessages`) - [*Получение списка сообщений из чата.*](./docs/README.md#Получение-списка-сообщений-из-чата)
|
||
- [x] `POST /messages` (`sendMessage`) - [*Отправка сообщения.*](./docs/README.md#Отправка-сообщения)
|
||
- [x] `PUT /messages` (`editMessage`) - [*Редактирование сообщения.*](./docs/README.md#Редактирование-сообщения)
|
||
- [x] `DELETE /messages` (`deleteMessage`) - [*Удаление сообщения.*](./docs/README.md#Удаление-сообщения)
|
||
- [x] `GET /messages/{messageId}` (`getMessageById`) - [*Получение сообщения по ID.*](./docs/README.md#Получение-сообщения-по-ID)
|
||
- [x] `GET /videos/{videoToken}` (`getVideoAttachmentDetails`) - [*Получение детальной информации о видео.*](./docs/README.md#Получение-детальной-информации-о-видео)
|
||
- [x] `POST /answers` (`answerOnCallback`) - [*Ответ на нажатие callback-кнопки.*](./docs/README.md#Ответ-на-нажатие-callback-кнопки)
|
||
|
||
#### Comments
|
||
|
||
- [x] `GET /messages/{messageId}/comments` (`getComments`) - [*Получение комментариев к посту.*](./docs/README.md#Получение-комментариев-к-посту)
|
||
- [x] `GET /messages/{messageId}/comments/{commentId}` (`getCommentById`) - [*Получение комментария по ID.*](./docs/README.md#Получение-комментария-по-ID)
|
||
- [x] `POST /messages/{messageId}/comments` (`sendComment`) - [*Отправка комментария.*](./docs/README.md#Отправка-комментария)
|
||
- [x] `PUT /messages/{messageId}/comments` (`editComment`) - [*Редактирование комментария.*](./docs/README.md#Редактирование-комментария)
|
||
- [x] `DELETE /messages/{messageId}/comments` (`deleteComment`) - [*Удаление комментария.*](./docs/README.md#Удаление-комментария)
|
||
|
||
## Лицензия
|
||
|
||
Данная библиотека распространяется под лицензией MIT - подробности см. в файле [LICENSE](LICENSE).
|