M
MAXHUB
pymax SDK / Документация

Документация pymax SDK

Установка, все 7 методов с примерами, получение WEB-токена, troubleshooting.

Версия 2.0maxapi-python v1.2.5+Commercial License
01

Установка

1. Установите базовую библиотеку

bash
pip install maxapi-python==1.2.5

2. Получите лицензионный ключ

Приобретите на maxhub.agency/tools или через бот @maxhub_agency_bot. После оплаты ключ придёт автоматически в формате MH-XXXX-XXXX-XXXX-XXXX.

3. Настройте переменную окружения

bash
export MAXHUB_LICENSE_KEY="MH-XXXX-XXXX-XXXX-XXXX"

Или в файле .env:

.env
MAXHUB_LICENSE_KEY=MH-XXXX-XXXX-XXXX-XXXX

4. Подключите SDK

python
# Импортируйте ПЕРЕД использованием maxapi
import license_check      # проверка лицензии
import pymax_patch         # патчи + новые методы

from maxapi import Bot

bot = Bot(token="YOUR_MAX_TOKEN")
💡 Подсказка
При запуске SDK автоматически проверит лицензию через License Server. Если ключ невалиден или истёк — скрипт не запустится.
02

Что исправлено

Восемь критических багов оригинальной библиотеки, которые ломали продакшн-сценарии.

1KeyError('chat')

invite/remove падали при определённых ответах сервера. Добавлен безопасный парсинг с fallback.

2Seq-коллизии

Одновременные запросы через SocketMixin вызывали коллизии seq-номеров. Добавлен asyncio.Semaphore(200).

3Двойной markdown

edit_message дважды парсил markdown, ломая форматирование. Исправлено.

4print(data) в set_password

Писал данные в stdout. Заменено на logger.debug.

5lz4 overflow

lz4.decompress падал на больших сообщениях. Добавлен динамический размер буфера.

6Notification crash

_send_notification_response падал при определённых payload. Обёрнут в safe mode.

7Database.create_all

Падал с custom session.db. Исправлено.

8Database safe mode

Все Database-методы обёрнуты в try/except с логированием.

03

Новые методы

Семь методов, которых нет в оригинальной библиотеке.

МЕТОД 1 / 7

create_channel()

Создаёт новый канал в MAX.

python
channel, message = await bot.create_channel(
    name="Мой канал",
    description="Описание канала",
    access="public"   # "public" или "private"
)
print(f"Канал создан: {channel.id}")
Возвращает:Кортеж (Channel, Message)
МЕТОД 2 / 7

promote_admin()

Назначает пользователя администратором канала.

⚠️ Важно
Требует WEB-токен! Socket API молча игнорирует promote для каналов.
python
success = await bot.promote_admin(
    chat_id=123456789,
    user_id=987654321,
    permissions=4026,         # полные права админа
    web_token="YOUR_WEB_TOKEN"
)
Возвращает:bool
МЕТОД 3 / 7

demote_admin()

Снимает администратора канала.

⚠️ Важно
Требует WEB-токен!
python
success = await bot.demote_admin(
    chat_id=123456789,
    user_id=987654321,
    web_token="YOUR_WEB_TOKEN"
)
Возвращает:bool
МЕТОД 4 / 7

set_chat_avatar()

Устанавливает аватарку чата или канала.

python
success = await bot.set_chat_avatar(
    chat_id=123456789,
    photo=open("avatar.jpg", "rb")
)
Возвращает:bool
МЕТОД 5 / 7

set_chat_banner()

Устанавливает баннер (обложку) канала.

python
success = await bot.set_chat_banner(
    chat_id=123456789,
    photo=open("banner.jpg", "rb")
)
Возвращает:bool
МЕТОД 6 / 7

forward_message()

Пересылает сообщение между чатами.

python
new_msg = await bot.forward_message(
    from_chat_id=111111111,
    message_id=42,
    to_chat_id=222222222,
    text="Дополнительный комментарий"  # опционально
)
Возвращает:Message
МЕТОД 7 / 7

send_typing()

Отправляет индикатор "печатает…".

python
await bot.send_typing(chat_id=123456789)
Возвращает:None
04

Как получить WEB-токен

WEB-токен нужен для promote_admin и demote_admin в каналах. Socket API (msgpack/TCP) молча игнорирует эти операции для каналов — они работают только через WebSocket JSON.

Пошаговая инструкция

  1. 1
    Откройте web.max.ru в браузере
  2. 2
    Войдите в свой аккаунт MAX
  3. 3
    Откройте DevTools (F12 или Ctrl+Shift+I)
  4. 4
    Перейдите на вкладку Network
  5. 5
    Отфильтруйте по WS (WebSocket)
  6. 6
    Найдите активное WebSocket-соединение
  7. 7
    Перейдите на вкладку Messages
  8. 8
    Найдите сообщение с opcode: 19
  9. 9
    В JSON найдите поле token — это ваш WEB-токен
Payload для promote
json
{
  "operation": "add",
  "type": "ADMIN",
  "permissions": 4026
}
Payload для demote
json
{
  "operation": "remove",
  "type": "ADMIN"
}
⚠️ Важно
send_fake_telemetry=False — обязательно, иначе дисконнект. WEB-токен отличается от обычного токена бота и может истекать — проверяйте периодически.
05

Troubleshooting

Частые проблемы и их решения.

«License key not found»
Проверьте переменную MAXHUB_LICENSE_KEY. Ключ должен быть в формате MH-XXXX-XXXX-XXXX-XXXX.
«License expired»
Продлите подписку на maxhub.agency/tools или через бот.
«Сервер лицензий недоступен»
SDK работает в grace-режиме. Проверьте интернет-соединение. Если проблема сохраняется — напишите в поддержку.
promote_admin не работает
Убедитесь, что передаёте web_token. Socket API молча игнорирует promote для каналов.
KeyError при invite/remove
Обновите pymax_patch до последней версии. Баг исправлен в v2.
lz4 decompress ошибки
Обновите pymax_patch. Добавлен динамический размер буфера.
Двойное форматирование в edit_message
Обновите pymax_patch. Баг с двойным парсингом markdown исправлен.
06

Поддержка

Telegram-бот

@maxhub_agency_bot

Сайт

maxhub.agency

Базовый план

Поддержка в Telegram-чате

Про план

Приоритетная поддержка <2ч + консультации по архитектуре

© 2026 MAXHUB · Все права защищены