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
))| Описание | Ссылка на пример |
|---|---|
| Как отправить сообщение | 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 |