MAX BOT API Client (Python)

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

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

API

Документацию по 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
    ))

---

Список примеров

Описание	Ссылка на пример
Как отправить сообщение	send_message.py
Как отправить сообщение асинхронно	get_messages_async.py
Как получить информацию о боте	get_bot.py
Как получить информацию о боте асинхронно	get_bot_async.py
Как загрузить файл	upload_file.py
Как загрузить файл асинхронно	upload_file_async.py
Как отправить файл	send_file.py
Как отправить файл асинхронно	send_file_async.py
Как получить входящее уведомление	get_updates.py
Как получить входящее уведомление асинхронно	get_updates_async.py

Список всех методов библиотеки

Метод API	Описание	Ссылка на документацию MAX	Ссылка на документацию MAX BOT API
bots.get_bot	Получает информацию о боте	get_bot	GetBot
bots.patch_bot	Изменяет информацию о боте		PatchBot
chats.get_chats	Возвращает список групповых чатов, в которых участвовал бот	get_chats	GetChats
chats.get_chat	Возвращает информацию о групповом чате по его ID	get_chat	GetChat
chats.edit_chat	Позволяет редактировать информацию о групповом чате	edit_chat	EditChat
chats.delete_chat	Удаляет групповой чат для всех участников	delete_chat	DeleteChat
chats.send_action	Позволяет отправлять следующие действия бота в групповой чат	send_action	SendAction
chats.get_pinned_message	Возвращает закрепленное сообщение в чате	get_pinned_message	GetPinnedMessage
chats.pin_message	Закрепляет сообщение в групповом чате	pin_message	PinMessage
chats.unpin_message	Удаляет закрепленное сообщение в групповом чате	unpin_message	UnpinMessage
chats.get_chat_membership	Возвращает членство бота в групповом чате	get_chat_membership	GetChatMembership
chats.leave_chat	Удаляет бота из группового чата	leave_chat	LeaveChat
chats.get_chat_admins	Возвращает список всех администраторов группового чата	get_chat_admins	GetChatAdmins
chats.set_chat_admins	Назначает участника группы администратором	set_chat_admins	SetChatAdmins
chats.delete_admin	Отменяет права администратора пользователя в групповом чате	delete_admin	DeleteAdmin
chats.get_chat_members	Возвращает список участников группового чата	get_chat_members	GetChatMembers
chats.add_members	Добавляет участников в групповой чат	add_members	AddMembers
chats.delete_member	Удаляет участника из группового чата	delete_member	DeleteMember
subscriptions.get_subscriptions	Возвращает список подписок на уведомления веб-хуков	get_subscriptions	GetSubscriptions
subscriptions.subscribe	Настраивает доставку событий бота через веб-хук	subscribe	Subscribe
subscriptions.unsubscribe	Отменяет подписку бота на получение обновлений через веб-хук	unsubscribe	Unsubscribe
subscriptions.get_updates	Получает входящие обновления	get_updates	GetUpdates
upload.upload_file	Загружает файл на серверы MAX для последующей передачи	upload_file	UploadFile
helpers.send_file	Упрощает отправку файлов, автоматически определяя URL или путь		SendFile
messages.get_messages	Возвращает информацию о сообщении или массив сообщений из чата	get_messages	GetMessages
messages.send_message	Отправляет текстовое или медиа-сообщение указанному пользователю или в чат	send_message	SendMessage
messages.edit_message	Редактирует текст или медиафайл ранее отправленного сообщения	edit_message	EditMessage
messages.delete_message	Удаляет сообщение из чата	delete_message	DeleteMessage
messages.get_message	Извлекает содержимое и метаданные конкретного сообщения по его ID	get_message	GetMessage
messages.get_video_info	Возвращает подробную информацию о прикрепленном видео	get_video_info	GetVideoInfo
messages.answer_callback	Отправляет ответ после того, как пользователь нажмет кнопку	answer_callback	AnswerCallback