maxbot-api-client-python — это библиотека для интеграции с MAX BOT API. Этот проект предоставляет структурированный интерфейс для взаимодействия с конфигурациями бота, управления сообщениями, отправки медиафайлов и подписки на события через long-polling.

Для использования библиотеки потребуется получить токен бота в консоли разработчика MAX bot.
Ознакомиться с инструкцией можно по ссылке.

Документацию по REST API MAX можно найти по ссылке dev.max.ru/docs-api. Библиотека является оберткой для REST API, поэтому документация по указанной выше ссылке также применима к используемым здесь моделям.

Документацию по MAX BOT API можно найти по ссылке green-api.com/max-bot-api/docs.

Убедитесь, что у вас установлен Python версии 3.12 или выше:

python --version

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

pip install maxbot-api-client-python

Импорт:

from maxbot_api_client_python import API, Config

Параметры конфигурации:

• base_url - Базовый URL-адрес серверов платформы MaxBot. Все методы API будут отправляться по этому корневому адресу. Актуальный адрес указан в официальной документации.
• token - Уникальный секретный ключ авторизации (API-ключ) вашего бота. Получить его можно в личном кабинете после регистрации или создании бота на платформе business.max.ru.
• ratelimiter - Встроенный ограничитель частоты запросов. Он контролирует количество исходящих запросов в секунду (RPS), защищая бота от блокировки со стороны сервера за превышение лимитов. Рекомендуемое значение — не менее 25.
• timeout - Максимальное время ожидания ответа от сервера (в секундах). Если сервер не ответит в течение этого времени, запрос будет завершен с ошибкой. Оптимальное значение — 30 секунд.

Как инициализировать клиент:

Использование контекстного менеджера (with / async with) гарантирует, что все сетевые соединения будут автоматически и безопасно закрыты по завершении работы.

from maxbot_api_client_python import API, Config

cfg = Config(
    base_url="https://platform-api.max.ru",
    token="YOUR_BOT_TOKEN",
    ratelimiter=25,
    timeout=30
)
# Синхронный режим:
with API(cfg) as bot:
    pass
# Асинхронный режим:
async with API(cfg) as bot:
    pass

Как получить информацию о боте:

• Ссылка на синхронный пример: get_bot.py

with API(cfg) as bot:
    response = bot.bots.get_bot()

• Ссылка на асинхронный пример: get_bot_async.py

async with API(cfg) as bot:
    response = await bot.bots.get_bot_async()

Как отправить сообщение:

• Ссылка на синхронный пример: send_message.py

with API(cfg) as bot:
    response = bot.messages.send_message(SendMessageReq(
        user_id=1234567890,
        text="Hello world!"
    ))

• Ссылка на асинхронный пример: send_message_async.py

async with API(cfg) as bot:
    response = await bot.messages.send_message_async(SendMessageReq(
        user_id=1234567890,
        text="Hello world from Async!"
    ))

Как легко отправить файл (по ссылке или локальный):

• Ссылка на синхронный пример: send_file.py

with API(cfg) as bot:
    response = bot.helpers.send_file(SendFileReq(
        chat_id=1234567890,
        text="Check this!",
        file_source="https://storage.yandexcloud.net/sw-prod-03-test/ChatBot/corgi.jpg"
    ))

• Ссылка на асинхронный пример: send_file_async.py

async with API(cfg) as bot:
    response = await bot.helpers.send_file_async(SendFileReq(
        chat_id=1234567890,
        text="Посмотри на этот файл!",
        file_source="https://storage.yandexcloud.net/sw-prod-03-test/ChatBot/corgi.jpg"
    ))

Как вручную загрузить файл (для кастомных вложений):

• Ссылка на синхронный пример: upload_file.py

with API(cfg) as bot:
    response = bot.uploads.upload_file(UploadFileReq(
        type=UploadType.image,
        file_path="examples/assets/file.jpg"
    ))

• Ссылка на асинхронный пример: upload_file_async.py

async with API(cfg) as bot:
    response = await bot.uploads.upload_file_async(UploadFileReq(
        type=UploadType.image,
        file_path="examples/assets/file.jpg"
    ))

Как получить входящее уведомление (Long Polling):

• Ссылка на синхронный пример: get_updates.py

with API(cfg) as bot:
    response = bot.subscriptions.get_updates(GetUpdatesReq(
        marker=0,
        timeout=30
    ))

• Ссылка на асинхронный пример: get_updates_async.py

async with API(cfg) as bot:
    response = await bot.subscriptions.get_updates_async(GetUpdatesReq(
        marker=0,
        timeout=30
    ))