Как создать бота в MAX: пошаговый гайд по Bot API

Bot API мессенджера MAX идеологически похож на Telegram Bot API: создаёте бота через специального системного бота, получаете токен, дальше ходите в REST-API и делаете что нужно. Но есть нюансы — другой эндпоинт, другая схема авторизации, несовпадающий набор методов. Разбираем пошагово: от регистрации до работающего бота на Python, плюс типовые ошибки и сравнение с Telegram.

Статья для разработчиков, которые хотят написать бота самостоятельно. Если цель — не «сделать своими руками», а «запустить бота для продаж в MAX за день», смотрите раздел в конце про готовые решения.

Что такое MAX Bot API

MAX Bot API — это HTTP REST-интерфейс для программного управления ботом. Через него бот получает входящие сообщения, отправляет ответы, управляет кнопками и клавиатурами, работает с медиа и пересылает файлы.

Базовый эндпоинт: https://botapi.max.ru/ (может также встречаться вариант platform.api.max.ru в документации). Авторизация — через токен, который вы получаете при создании бота. Формат запросов — JSON, ответ — JSON.

Ключевое отличие от Telegram: в MAX Bot API методы и структуры пока отличаются. Если вы переносите бота с Telegram, держите в голове, что прямое копирование не сработает — нужно читать документацию MAX и править запросы.

Шаг 1: создаём бота через @MasterBot

В MAX роль BotFather выполняет @MasterBot — системный бот, который управляет вашими ботами. Процедура такая:

Установите MAX и авторизуйтесь через VK ID.
В поиске найдите @MasterBot (или перейдите по прямой ссылке через сайт MAX).
Отправьте команду /create.
Введите имя бота (отображается пользователям) и юзернейм (должен заканчиваться на _bot).
Получите токен вида abcdefg.hijklmn.opqrstuvwxyz — это ваш ключ доступа. Храните в секрете.

Сразу настройте команду /setdescription — текст, который видит пользователь при открытии бота, и /setphoto — аватар. Это базовые, но заметные на UX вещи.

Шаг 2: первый запрос к API

Проверим, что токен работает. Вызываем метод /getMe — возвращает информацию о боте:

curl "https://botapi.max.ru/getMe?access_token=ВАШ_ТОКЕН"

Ответ:

{
  "bot_id": 12345,
  "name": "Мой бот",
  "username": "my_awesome_bot",
  "first_name": "Мой"
}

Если ответ пришёл — всё работает. Если 401 Unauthorized — токен неверный или не передан в правильном формате. Проверьте, что в запросе — именно access_token, а не token или api_key.

Шаг 3: отправка сообщения

Простой пример на Python — отправка сообщения конкретному пользователю. Нужен user_id (получите его, когда пользователь сам напишет боту — в структуре входящего сообщения).

import requests

TOKEN = "ВАШ_ТОКЕН"
URL = "https://botapi.max.ru/messages"

def send_message(user_id, text):
    params = {"access_token": TOKEN, "user_id": user_id}
    data = {"text": text}
    r = requests.post(URL, params=params, json=data)
    return r.json()

print(send_message(user_id=12345, text="Привет, я бот в MAX"))

Сообщение придёт пользователю в обычный чат с ботом. Если нужны кнопки, картинка, файл — передаются дополнительные поля в data (смотрите в документации MAX раздел attachments).

Шаг 4: приём входящих сообщений

Два варианта — long polling и webhook.

Long polling. Бот сам регулярно опрашивает API на предмет новых сообщений через метод /updates:

def get_updates(offset=0):
    params = {"access_token": TOKEN, "marker": offset, "timeout": 30}
    r = requests.get("https://botapi.max.ru/updates", params=params)
    return r.json()

marker = 0
while True:
    resp = get_updates(marker)
    for upd in resp.get("updates", []):
        print(upd)
        marker = upd["timestamp"] + 1

Плюс long polling — не нужен публичный IP и HTTPS. Минус — бот не работает, когда скрипт упал.

Webhook. Вы регистрируете URL, и MAX сам присылает события. Для этого нужен публичный HTTPS-сервер. Регистрация:

requests.post(
    "https://botapi.max.ru/subscriptions",
    params={"access_token": TOKEN},
    json={"url": "https://example.com/max-webhook"}
)

На своём сервере поднимаете HTTP-эндпоинт, принимаете POST с JSON, обрабатываете, отвечаете 200. Для продакшена — именно webhook, он стабильнее и быстрее.

Шаг 5: обработка пользовательских команд

Входящее сообщение приходит в структуре вида:

{
  "update_type": "message_created",
  "timestamp": 1713859200000,
  "message": {
    "sender": {"user_id": 12345, "name": "Иван"},
    "body": {"text": "/start"},
    "recipient": {"chat_id": 67890}
  }
}

Базовая обработка — парсим текст, реагируем командой:

def handle(update):
    msg = update["message"]
    text = msg["body"]["text"]
    user_id = msg["sender"]["user_id"]

    if text == "/start":
        send_message(user_id, "Привет! Я бот, напишите, чем помочь.")
    elif text == "/price":
        send_message(user_id, "Подскажите, какая услуга интересует — пришлю прайс.")
    else:
        send_message(user_id, f"Вы написали: {text}")

Этого достаточно для MVP-бота с парой команд. Дальше — добавляете клавиатуры, отправку картинок, работу с базой данных, логику опросника и так далее.

Типовые ошибки

1. Неверный токен. Токен выдаётся один раз и не показывается повторно. Если потеряли — перевыпустите через /revoke в @MasterBot, старый перестанет работать.

2. Webhook не принимает запросы. Частая причина — сертификат. MAX требует валидный HTTPS без self-signed. Используйте Let's Encrypt или Cloudflare.

3. Лимиты на отправку. Базовый лимит — около 20–30 сообщений в секунду на бота, при рассылках — жёстче. При превышении приходит 429, обрабатывайте с retry + backoff.

4. Формат медиа. Размер и форматы файлов ограничены; перед отправкой проверяйте, что файл помещается в лимиты. Документацию смотрите в разделе attachments.

5. Обработка ошибок API. Ответ всегда JSON, при ошибке — есть поле code и message. Не полагайтесь только на HTTP-статус, смотрите тело.

Чем MAX Bot API отличается от Telegram

Если вы делали ботов для Telegram, основные расхождения:

Эндпоинт и авторизация. Telegram — api.telegram.org/bot<TOKEN>/method, MAX — botapi.max.ru/method?access_token=<TOKEN>.
Обновления — другой формат. В Telegram update — плоская структура, в MAX — вложенные объекты с message.sender, message.body. Парсеры не совместимы.
Inline-режим и часть клавиатур в MAX ограничены или в бете. Не закладывайтесь на них без проверки.
Verified-галочка и интеграции. В MAX у бота может быть верификация, а у пользователя — подтверждённая личность через VK ID. В Telegram такого нет.

Сам процесс разработки (получение токена, отправка, приём) — похож; отличия больше в деталях.

Когда писать бота самому, а когда — взять готовое

Самописный бот на Bot API имеет смысл в двух ситуациях: у вас есть разработчик и узкая нестандартная логика, которой нет в готовых решениях, либо бот — часть вашего продукта, и вы хотите контролировать код целиком.

Готовое решение окупается, если задача — типовая: отвечать на входящие от клиентов, квалифицировать лидов, передавать в CRM. В этом случае самописный бот — это 2–4 недели разработки плюс поддержка, тогда как готовый AI-агент подключается за день и обновляется бесплатно.

В Leadarr MAX уже подключён как канал рядом с Авито, Telegram и WhatsApp. Подробнее, что именно делает AI-агент в MAX, — в отдельной статье.

Частые вопросы

Нужно ли юрлицо для создания бота?

Для создания — нет, достаточно обычного аккаунта MAX. Для верификации и получения «галочки» — да, юрлицо или ИП с регистрацией на МСП.рф или приложением в RuStore.

Есть ли лимиты на количество ботов на аккаунт?

Да — в 2026 базовый лимит 10 ботов на аккаунт, можно запросить увеличение у службы поддержки. Для большинства задач 10 хватает с запасом.

Можно ли бота на бессерверной архитектуре (Cloud Functions, Lambda)?

Да, стандартный сценарий. Webhook направляете на HTTPS-эндпоинт вашей функции, в функции принимаете JSON, отвечаете. Платите только за вызовы.

Есть ли официальная библиотека для Python/Node?

На апрель 2026 — нет официальных SDK от VK, есть несколько сторонних обёрток разной зрелости. Для продакшена обычно проще работать напрямую через requests/axios — API достаточно простой.

Как тестировать бота локально без публичного HTTPS?

Long polling (/updates) — работает без публичного IP, подходит для разработки. Для тестов webhook — можно поднять туннель через ngrok или cloudflared.

Запустить бота в MAX без разработки

Если у вас задача не «написать бота», а «поставить в MAX бота, который продаёт» — попробуйте Leadarr 7 дней без карты. Подключение MAX — пара часов, дальше AI-агент ведёт диалог по вашей базе знаний и передаёт в CRM.

Смежные материалы: