maxbot-api-client-python 1.1.2

Python client for MAX Bot API with Sync and Async support

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

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

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

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

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

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

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

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

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

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

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

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

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

with API(cfg) as bot:
    response = bot.helpers.SendFile(
        chat_id=1234567890,
        text="Check this!",
        file_source="[https://http.cat/200.jpg](https://http.cat/200.jpg)"
    )

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

async with API(cfg) as bot:
    response = await bot.helpers.SendFileAsync(
        chat_id=1234567890,
        text="Посмотри на этот файл!",
        file_source="[https://http.cat/200.jpg](https://http.cat/200.jpg)"
    )

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

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

from maxbot_api_client_python.types.constants import UploadType

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

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

from maxbot_api_client_python.types.constants import UploadType

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

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

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

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

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

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

---

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

Описание	Ссылка на пример
Как отправить сообщение	SendMessage.py
Как отправить сообщение асинхронно	SendMessageAsync.py
Как получить информацию о боте	GetBot.py
Как получить информацию о боте асинхронно	GetBotAsync.py
Как загрузить файл	UploadFile.py
Как загрузить файл асинхронно	UploadFileAsync.py
Как отправить файл	SendFile.py
Как отправить файл асинхронно	SendFileAsync.py
Как получить входящее уведомление	GetUpdates.py
Как получить входящее уведомление асинхронно	GetUpdatesAsync.py

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

Метод API	Описание	Ссылка на документацию MAX	Ссылка на документацию библиотеки
Bots.GetBot	Получает информацию о боте	GetBot	GetBot
Bots.PatchBot	Изменяет информацию о боте		PatchBot
Chats.GetChats	Возвращает список групповых чатов, в которых участвовал бот	GetChats	GetChats
Chats.GetChat	Возвращает информацию о групповом чате по его ID	GetChat	GetChat
Chats.EditChat	Позволяет редактировать информацию о групповом чате	EditChat	EditChat
Chats.DeleteChat	Удаляет групповой чат для всех участников	DeleteChat	DeleteChat
Chats.SendAction	Позволяет отправлять следующие действия бота в групповой чат	SendAction	SendAction
Chats.GetPinnedMessage	Возвращает закрепленное сообщение в чате	GetPinnedMessage	GetPinnedMessage
Chats.PinMessage	Закрепляет сообщение в групповом чате	PinMessage	PinMessage
Chats.UnpinMessage	Удаляет закрепленное сообщение в групповом чате	UnpinMessage	UnpinMessage
Chats.GetChatMembership	Возвращает членство бота в групповом чате	GetChatMembership	GetChatMembership
Chats.LeaveChat	Удаляет бота из группового чата	LeaveChat	LeaveChat
Chats.GetChatAdmins	Возвращает список всех администраторов группового чата	GetChatAdmins	GetChatAdmins
Chats.SetChatAdmins	Назначает участника группы администратором	SetChatAdmins	SetChatAdmins
Chats.DeleteAdmin	Отменяет права администратора пользователя в групповом чате	DeleteAdmin	DeleteAdmin
Chats.GetChatMembers	Возвращает список участников группового чата	GetChatMembers	GetChatMembers
Chats.AddMembers	Добавляет участников в групповой чат	AddMembers	AddMembers
Chats.DeleteMember	Удаляет участника из группового чата	DeleteMember	DeleteMember
Subscriptions.GetSubscriptions	Возвращает список подписок на уведомления веб-хуков	GetSubscriptions	GetSubscriptions
Subscriptions.Subscribe	Настраивает доставку событий бота через веб-хук	Subscribe	Subscribe
Subscriptions.Unsubscribe	Отменяет подписку бота на получение обновлений через веб-хук	Unsubscribe	Unsubscribe
Subscriptions.GetUpdates	Получает входящие обновления	GetUpdates	GetUpdates
Upload.UploadFile	Загружает файл на серверы MAX для последующей передачи	UploadFile	UploadFile
Helpers.SendFile	Упрощает отправку файлов, автоматически определяя URL или путь		SendFile
Messages.GetMessages	Возвращает информацию о сообщении или массив сообщений из чата	GetMessages	GetMessages
Messages.SendMessage	Отправляет текстовое или медиа-сообщение указанному пользователю или в чат	SendMessage	SendMessage
Messages.EditMessage	Редактирует текст или медиафайл ранее отправленного сообщения	EditMessage	EditMessage
Messages.DeleteMessage	Удаляет сообщение из чата	DeleteMessage	DeleteMessage
Messages.GetMessage	Извлекает содержимое и метаданные конкретного сообщения по его ID	GetMessage	GetMessage
Messages.GetVideoInfo	Возвращает подробную информацию о прикрепленном видео	GetVideoInfo	GetVideoInfo
Messages.AnswerCallback	Отправляет ответ после того, как пользователь нажмет кнопку	AnswerCallback	AnswerCallback