Когда я писал своего первого более-менее серьезного бота под Max, случилась классика. Я и мой ИИ-ассистент (Cursor) пишем код, строго опираясь на официальную документацию Max API. Запускаю — падает. Сижу по 5-6 итераций, пытаюсь отдебажить базовый функционал, который под ту же Телегу пишется с закрытыми глазами.

В какой-то момент меня это достало. Я понял, что проблема не во мне и не в галлюцинациях нейронки. Я просто включил логирование всех входящих POST-запросов и стал дампить реальные вебхуки, которые прилетают от серверов Max. Открыв логи, я понял, почему мы так долго буксовали: то, что написано в документации, и то, что прилетает по факту — это две большие разницы. А слепая привычка писать архитектуру под Telegram Bot API делает только хуже.

Различия с официальной документацией Max API (Docs vs Реальность)

1. Обертка (Update Wrapper): В доках написано, что тебе приходит чистый объект Message. В реальности всё завернуто в мета-контейнер: корень JSON содержит update_type и user_locale, а сам message уже запрятан внутри.

2. Таймстемпы: Доки обещают классический «Unix-time» (что логично воспринимать как секунды). В реальности Макс шлет таймстемпы в миллисекундах. Парсишь в лоб как секунды — улетаешь в 57000-й год.

3. Путь к тексту: В доках указано просто body.text. В реальности текст закопан глубоко по пути: payload['message']['body']['text'].

Отличия от Telegram Bot API (TG vs Max)

1. Где лежит юзер: В Телеге мы берем инициатора из message.from. В Максе это поле называется sender. Причем у обычных юзеров там часто вообще нет username, опираться приходится только на поле name.

2. Архитектура кнопок (Callbacks): В Телеге при нажатии кнопки message вложено внутрь CallbackQuery. В Максе инфа о нажатии (callback) и само сообщение (message) приходят на одном уровне, как братья. ID того, кто нажал кнопку, нужно искать в callback.user.user_id, а не в отправителе сообщения.

3. Где лежат клавиатуры: В Телеге кнопки живут в удобном отдельном поле reply_markup. В Максе клавиатура — это просто одно из вложений. Она лежит в массиве attachments (с типом inline_keyboard), прямо вперемешку с отправленными картинками.

Как отучить ИИ галлюцинировать (и спасти свои нервы)

Всю эту боль я собрал в единый файл-шпаргалку: MAX_API_Real_Payloads_2026.md. Поначалу я просто держал его открытым на соседнем мониторе, чтобы каждый раз сверяться: «А не бьюсь ли я сейчас лбом об один из этих шести пунктов?».

Но основную разработку я веду в Cursor, и меня дико бесило, что ассистент постоянно пытается подсунуть мне телеграмовские структуры. Решение оказалось до смешного простым. Я положил этот файл в корень проекта и прописал жесткое условие в .cursorrules: «Прежде чем писать любой код для интеграции с Max API, обязательно спарси файл MAX_API_Real_Payloads_2026.md и используй структуры только оттуда».

Работа пошла х2 быстрее. Я перестал тратить часы на дебаг абсолютно тривиального функционала.

Поняв, что эта проблема массовая, я пошел в опенсорс. Сделал Pull Request в самую популярную Python-библиотеку под Max — maxapi. Автор оценил проблему, вмержил PR, и теперь шпаргалка официально лежит у них в папке /docs.

Затем закинул аналогичный PR ребятам из официального SDK на Go — max-bot-api-client-go. Они тоже приняли изменения, файл теперь живет у них в директории /schemes.

----------------------------------------------------------------------------

Готовая таблетка: Boilerplate без боли

Поняв всю эту архитектурную дичь, я решил, что парсить многоуровневые словари через dict.get() и ловить KeyError — это путь в никуда. Поэтому я собрал max-bot-aio-template. Это не "hello world", а нормальный стартовый каркас для ботов, ориентированный на строгую типизацию.

Что под капотом:

• Pydantic V2 на входе: Никаких сырых JSON. Все кривые ответы MAX API (с их миллисекундами и спрятанными текстами) сразу валидируются и превращаются в предсказуемые объекты.

• Зашитый AI-контекст: Тот самый MAX_API_Real_Payloads_2026.md и .cursorrules уже лежат в репозитории. Клонируешь, открываешь в Cursor/Copilot — и нейронка с ходу пишет правильный код под Макс.

• Изоляция логики (Layered Architecture): Бизнес-логика полностью отвязана от API мессенджера. Если завтра Макс выкатит v2, переписывать придется только слой Delivery.

• Джентльменский стек: Python 3.12, асинхронная SQLAlchemy 2.0, Redis и настроенный Docker с миграциями.

? Ссылка на файл: https://github.com/Danya2904/max-bot-aio-template/blob/main/docs/MAX_API_Real_Payloads_2026.md

Ссылка выше это файл Paa max-bot-aio-template на GitHub

Буду рад звездам и форкам. Если Макс снова поменяет API (а он их рано или поздно поменяет) — давайте контрибьютить новые пейлоады вместе, чтобы поддерживать актуальный стандарт и не дебажить поодиночке.

? А если хотите обсудить архитектуру под новую платформу — залетайте в наш профильный чат: Max Chat.