⚡ Быстрый старт

За 5 минут — от нуля до работающего клиента.

1. Установка зависимостей

pip install msgpack aiohttp lz4

2. Структура проекта

MAX/
├── maxapi/
│   ├── __init__.py       # реэкспорт MaxClient
│   ├── client.py         # основной класс MaxClient
│   ├── constants.py      # OpCode, API_URL, настройки
│   ├── protocol.py       # класс Packet (сериализация)
│   ├── transport.py      # TCP/SSL Connection
│   └── session.py        # Session (хранение токена)
└── my_session.json       # создаётся автоматически после входа

3. Первый вход (SMS)

При первом запуске сессии ещё нет — нужно войти через SMS-код:

import asyncio
from maxapi import MaxClient

async def main():
    client = MaxClient("my_session")   # session = "my_session.json"
    await client.connect()

    # Запрашиваем SMS-код
    sent = await client.send_code("+79999999999")
    print(f"Код отправлен, длина: {sent.code_length}")

    # Вводим код и входим
    code = input("Введите код из SMS: ")
    result = await client.sign_in(code)

    if result.success:
        print(f"Вход выполнен! UID = {result.uid}")
    elif result.needs_registration:
        print("Аккаунт не найден, нужна регистрация")
        result = await client.sign_up("Иван", "Петров")

    await client.disconnect()

asyncio.run(main())

✅

После успешного входа сессия сохраняется в my_session.json. При следующем запуске connect() автоматически восстановит её — повторный ввод кода не нужен.

4. Повторный запуск (с сохранённой сессией)

import asyncio
from maxapi import MaxClient

async def main():
    async with MaxClient("my_session") as client:
        # connect() + auto-login уже произошли
    # client.me / cached_chats заполнены только если LOGIN действительно успешен
        print(f"Привет, {client.me['name']}! UID={client.uid}")

        chats = client.cached_chats
        print(f"Чатов: {len(chats)}")
        for chat in chats[:5]:
            print(f"  [{chat['type']}] id={chat['id']}")

asyncio.run(main())

ℹ️

client.me и client.cached_chats — это именно кэш успешного LOGIN. Если соединение уже открыто, но клиент ещё не авторизован, эти свойства останутся пустыми. Для свежего профиля с сервера используйте await client.fetch_profile().

5. Отправить сообщение

async with MaxClient("my_session") as client:
    result = await client.send_message(
        chat_id=34540359,
        text="Привет от MAX API! 🚀"
    )
    msg = result["message"]
    msg_id = msg.get("msgId") or msg.get("id")
    print(f"Отправлено! id={msg_id}, time={msg['time']}")

ℹ️

Сервер возвращает полный объект сообщения с назначенным ID и временной меткой. На практике идентификатор может приехать как в id, так и в msgId, поэтому в примерах лучше поддерживать оба ключа.

⚠️

Часть методов библиотеки возвращает сырой ответ сервера. Ошибка часто приходит не как Python-исключение, а как обычный dict с полем error. Это нужно проверять вручную.

6. Прочитать историю чата

async with MaxClient("my_session") as client:
    chats = client.cached_chats
    chat_id = chats[0]["id"]

    data = await client.get_chat_history(chat_id=chat_id, count=20)
    for msg in data.get("messages", []):
        print(f"[{msg['sender']}]: {msg.get('text','')[:80]}")

7. Context manager vs ручное управление

Способ	Когда использовать
`async with MaxClient(...) as c`	Скрипты, короткие задачи — connect/disconnect автоматически
`await client.connect() … await client.disconnect()`	Боты с длительным аптаймом, когда нужен ручной контроль

Что дальше?

🔑 Авторизация ✉️ Сообщения 💬 Чаты 🔢 Все OpCode'ы