⚡ События (Push-уведомления)

Сервер MAX поддерживает постоянное TCP-соединение и сам толкает пакеты при новых событиях (входящие сообщения, статусы, уведомления о наборе и т.д.). Никакого polling'а не нужно.

Как это работает

1. Клиент подключается и логинится — await client.connect()
2. Регистрируются обработчики через декораторы @client.on_message / @client.on(opcode)
3. Вызывается await client.run_until_disconnected() — блокирует и слушает
4. При входящем пакете библиотека строит типизированный объект и вызывает обработчик в отдельной задаче

Базовый шаблон юзербота

import asyncio
from maxapi import MaxClient
from maxapi.types import Message

client = MaxClient("my_session")  # загружает my_session.json

@client.on_message
async def handler(msg: Message):
    if not msg.is_outgoing:
        await msg.reply("Привет от MAX API!")

asyncio.run(client.run())  # connect() + run_until_disconnected()

@client.on_message
async def on_msg(msg: Message):
    if msg.is_outgoing:
        return  # игнорируем собственные
    print(f"Новое от {msg.sender_id}: {msg.text}")
    await msg.reply("Получено!")

from maxapi import OpCode
from maxapi import TypingEvent, PresenceEvent, ReactionEvent

@client.on(OpCode.NOTIF_TYPING)
async def on_typing(event: TypingEvent):
    print(f"Печатает: {event.sender_id} в чате {event.chat_id}")

@client.on_presence
async def on_presence(event: PresenceEvent):
    print(f"{event.user_id} {'онлайн' if event.is_online else 'оффлайн'}")

@client.on_reaction
async def on_reaction(event: ReactionEvent):
    print(f"Реакция {event.top_reaction} на сообщение {event.message_id}")

@client.on_message
async def logger(msg): print(msg)

@client.on_message
async def responder(msg):
    if not msg.is_outgoing:
        await msg.reply("Авто-ответ")

await client.connect()
await client.run_until_disconnected()

Класс Message

Объект передаваемый в @on_message хендлер.

Методы

Класс TypingEvent

Объект передаваемый в @client.on(OpCode.NOTIF_TYPING) хендлер.

Класс PresenceEvent

Объект передаваемый в @client.on_presence хендлер (NOTIF_PRESENCE, opcode 132).

@client.on_presence
async def on_presence(event: PresenceEvent):
    if event.is_online:
        print(f"Пользователь {event.user_id} вошёл онлайн")

Класс ReactionEvent

Объект передаваемый в @client.on_reaction хендлер (NOTIF_MSG_REACTIONS_CHANGED, opcode 155).

@client.on_reaction
async def on_reaction(event: ReactionEvent):
    print(f"Реакция {event.top_reaction} на сообщение {event.message_id}")

Push-опкоды сервера

Все входящие уведомления имеют opcode ≥ 128 и никогда не являются ответами на наши запросы.

Wire-формат NOTIF_MESSAGE (opcode 128)

Пример реального пакета, пойманного во время теста:

{
  "chatId":        63530148,
  "message": {
    "id":      116273637059727804,
    "time":    1774194113898,
    "type":    "USER",
    "sender":  7162153,
    "cid":     567919839690875,
    "text":    "Привет!",
    "attaches": []
  },
  "prevMessageId": 116273584104764698,
  "ttl":           false,
  "unread":        0,
  "mark":          1774194113898
}