geckon01/max-bot-api-client-php
1
0
Fork 0
mirror of https://github.com/BushlanovDev/max-bot-api-client-php.git synced 2026-08-18 23:52:54 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
d2aedc090fb9f87b4ad8f1b1625b9b01160ffc02
max-bot-api-client-php/docs/README.md
T
Alex d2aedc090f Documentation
2025-08-21 19:24:38 +03:00

18 KiB
Raw Blame History

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

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

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

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

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

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

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

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

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

При не необходимости опубликовать конфиг выполните следующую команду

php artisan vendor:publish --provider="BushlanovDev\MaxMessengerBot\Laravel\MaxBotServiceProvider"

Для работы вам потребуется внести следующие настройки в .env

MAXBOT_ACCESS_TOKEN=your_bot_access_token_here
MAXBOT_WEBHOOK_SECRET=your_webhook_secret_here
MAXBOT_LOGGING_ENABLED=true

Инициализация бота

Единственной обязательной настройкой является токен вашего бота.
⚠️ Никогда, и ни при каких обстоятельствах не храните токен в коде. ⚠️
Используйте переменные окружения!

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

use BushlanovDev\MaxMessengerBot\Api;

$api = new Api('YOUR_BOT_API_TOKEN');

Так же вы можете создать экземпляр бота гибко настроив все зависимости под свои нужды.

$api = new Api(
    client: new Client(...),
    modelFactory: new ModelFactory(),
    logger: new YourPsrLogger(),
);

Информация о боте

Получение информации о боте

$botInfo = $api->getBotInfo();

Редактирование информации о боте

Обратите внимание что данный метод отправляется PATCH запросом. Это значит, что будут обновлены только переданные поля.
В следующем примере мы изменяем только название бота и отчистим его описание. Остальные поля останутся неизменными.

$botInfo = $api->editBotInfo(
    new BotPatch(
        name: 'Супер бот',
        description: null,
    )
);

Чаты

Получение списка всех чатов бота

$chats = $api->getChats(
    count: 10, // Количество запрашиваемых чатов
    marker: 2, // Указатель на следующую страницу данных. Для первой страницы передайте null
);

Получение информации о чате по ссылке

$chat = $api->getChatByLink('@super_chat'); // Публичная ссылка на чат или username пользователя

Получение информации о чате по ID

$chat = $api->getChat(12345);

Редактирование информации о чате

$chat = $api->editChat(
    chatId: 12345,
    chatPatch: new ChatPatch(
        title: 'Новое название чата',
    ),
);

Удаление чата

$api->deleteChat(12345);

Отправка действия в чат

$api->sendAction(
    chatId: 12345,
    action: SenderAction::SendingVideo,
);

Получение закрепленного сообщения

$message = $api->getPinnedMessage(12345);

Закрепление сообщения

$api->pinMessage(
    chatId: 12345,
    messageId: 54321,
    notify: true,
);

Открепление сообщения

$api->unpinMessage(12345);

Получение информации о членстве бота в чате

$chatMember = $api->getMembership(12345);

Выход бота из чата

$api->leaveChat(12345);

Получение администраторов чата

$adminsChatMemberList = $api->getAdmins(12345);

Назначение администраторов чата

$chatMemberList = $api->addAdmins(
    chatId: 12345,
    admins: [
        new ChatAdmin(123, [ChatAdminPermission::ReadAllMessages]),
        new ChatAdmin(456, [ChatAdminPermission::Write]),
    ],
);

Снятие прав администратора

$api->deleteAdmin(
    chatId: 12345,
    userId: 123,
);

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

$chatMemberList = $api->getMembers(12345);

Добавление участников в чат

$api->addMembers(
    chatId: 12345,
    userIds: [123, 456],
);

Удаление участника из чата

$api->deleteMember(
    chatId: 12345,
    userId: 123,
    block: true, // Пользователь будет заблокирован в чате
);

Получение обновлений

Получение списка Webhook-подписок

$subscriptions = $api->getSubscriptions();

Создание Webhook-подписки

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

Удаление Webhook-подписки

$api->unsubscribe('https://example.com/webhook');

Получение обновлений через Long-Polling

$updateList = $api->getUpdates(
    limit: 10,                           // Максимальное количество обновлений для получения [1-1000] (необязательно) 
    timeout: 10,                         // Таймаут в секундах [0-90] (необязательно)
    marker: 123,                         // Если передан, бот получит обновления, которые еще не были получены (необязательно)
    types: [UpdateType::MessageCreated], // Типы обновлений которые вы хотите получать (необязательно)
);

Загрузка файлов

Получение URL для загрузки файла

$uploadEndpoint = $api->getUploadUrl(UploadType::Video);
// Далее вы можете загрузить файл по полученному URL самостоятельно или воспользоваться методом Client::upload()

Загрузка файла

Данный метод получит URL для загрузки, отправит файл и вернет готовый аттачмент

$photoAttachmentRequest = $api->uploadAttachment(
    type: UploadType::Image,
    filePath: __DIR__ . '/test.jpg',
);

Сообщения

Получение списка сообщений из чата

$messages = $api->getMessages(
    chatId: 12345,          // ID чата, чтобы получить сообщения из определённого чата (необязательно)
    messageIds: [123, 456], // Список ID сообщений, которые нужно получить (необязательно)
    from: 10,               // Время начала для запрашиваемых сообщений [Unix timestamp] (необязательно)
    to: 20,                 // Время окончания для запрашиваемых сообщений [Unix timestamp] (необязательно)
    count: 10,              // Максимальное количество сообщений в ответе [1-100] (необязательно)
);

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

$fileAttachmentRequest = $api->uploadAttachment(
    type: UploadType::File,
    filePath: __DIR__ . '/test.pdf',
);

$message = $api->sendMessage(
    userId: 12345,                      // Если вы отправляете сообщение пользователю, укажите его ID (необязательно)
    chatId: 54321,                      // Если сообщение отправляется в чат, укажите его ID (необязательно)
    text: 'Привет мир!',                // Текст сообщения (необязательно)
    attachments: [                      // Прикрепленные элементы (необязательно)
        $fileAttachmentRequest,
        PhotoAttachmentRequest::fromUrl('https://example.com/image.jpg'),
        new LocationAttachmentRequest(
            latitude: 55.7520233,
            longitude: 37.6174994,
        ),
    ],
    format: MessageFormat::Markdown,    // Формат сообщения Markdown или HTML (необязательно)
    link: null,                         // Ссылка на сообщение (необязательно)
    notify: true,                       // Если false, участники чата не будут уведомлены (необязательно)
    disableLinkPreview: false,          // Если false, сервер не будет генерировать превью для ссылок в тексте сообщения (необязательно)
);

Редактирование сообщения

$api->editMessage(
    messageId: 12345,
    text: 'Привет мир!',
    attachments: null,
    format: null,
    link: null,
    notify: true,
);

Удаление сообщения

$api->deleteMessage(12345);

Получение сообщения по ID

$message = $api->getMessageById(12345);

Получение детальной информации о видео

$videoAttachmentDetails = $api->getVideoAttachmentDetails('some-video-token');

Ответ на нажатие callback-кнопки

Этот метод используется для отправки ответа после того, как пользователь нажал на кнопку.
Ответом может быть обновленное сообщение и/или одноразовое уведомление для пользователя.

$api->answerOnCallback(
    callbackId: 'some-callback-id',    // Идентификатор кнопки, по которой пользователь кликнул
    notification: 'some-notification', // Заполните это, если хотите просто отправить одноразовое уведомление пользователю (необязательно)
    text: 'some-text',                 // Новый текст сообщения (необязательно)
    attachments: null,                 // Вложения сообщения. Если пусто, все вложения будут удалены (необязательно)
    link: null,                        // Ссылка на сообщение (необязательно)
    format: null,                      // Формат сообщения Markdown или HTML (необязательно)
    notify: true,                      // Заполните это, если хотите просто отправить одноразовое уведомление пользователю (необязательно)
);
Reference in New Issue View Git Blame Copy Permalink