Python MAX BOT API Library#

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

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

Установка#

Убедитесь, что у вас установлена версия Python не ниже 3.12

python --version

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

pip install maxbot-api-client-python

Импорт:

from maxbot_api_client_python import API, Config

Использование и примеры#

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

BaseURL - Базовый URL-адрес серверов платформы MaxBot. Все методы API будут маршрутизироваться по этому корневому адресу. Актуальный адрес указан в официальной документации.
Token - Уникальный секретный ключ авторизации (API-ключ) вашего бота. Получить его можно в личном кабинете после регистрации или создании бота на платформе business.max.ru. Читайте перед началом работы, чтобы получить токен.
RateLimiter - Встроенный ограничитель частоты запросов. Он контролирует количество исходящих запросов в секунду (RPS), защищая бота от блокировки со стороны сервера за превышение лимитов. Рекомендуемое значение — не менее 25, но не более 30.
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

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

Синхронный пример:

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

Асинхронный пример:

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

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

Синхронный пример:

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

Асинхронный пример:

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

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

Синхронный пример:

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"
    ))

Асинхронный пример:

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"
    ))

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

Синхронный пример:

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

Асинхронный пример:

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

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

Синхронный пример:

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

Асинхронный пример:

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

Документация по методам сервиса#

Документация по методам сервиса