Подключение бота в MAX: инструкция для разработчиков

MAX (ранее VK Макс) — это мощный мессенджер с открытой платформой для разработки ботов. Если вы хотите автоматизировать общение с пользователями, подключить платежи, заказы или просто развлекательного ассистента — эта статья для вас. Мы разберём полный цикл: от регистрации бота до деплоя на продакшен.

Что такое бот в MAX и зачем он нужен

Бот — это программа, которая автоматически отвечает пользователям в чате. В MAX боты могут обрабатывать текст, кнопки, команды, а также отправлять медиафайлы. С помощью API ботов вы можете интегрировать внешние сервисы: CRM, базы данных, платёжные шлюзы. Боты подходят для поддержки клиентов, заказа товаров, опросов и многого другого.

Подготовка к созданию бота

Перед тем как подключить бота, убедитесь, что у вас есть:

• Аккаунт в MAX (можно зарегистрироваться в приложении).
• Базовые знания HTTP и JSON (для работы с API).
• Сервер или облачная платформа (например, Heroku, AWS, Yandex Cloud) для хостинга бота.

Шаг 1: Регистрация бота в каталоге

Откройте приложение MAX, перейдите в Настройки → Разработчикам → Мои боты. Нажмите кнопку «Создать бота». Заполните поля:

• Имя бота — отображается в чате (например, «Помощник Макс»).
• Описание — кратко о функциях.
• Аватар — загрузите картинку (рекомендуется 512×512 px).

После создания вы получите токен бота — секретный ключ для авторизации запросов к API. Храните его в безопасности, не публикуйте в открытом доступе.

Шаг 2: Настройка webhook для получения обновлений

Чтобы бот реагировал на сообщения, нужно установить webhook — URL вашего сервера, куда MAX будет отправлять POST-запросы с данными о новых событиях. Выполните запрос к API:

POST https://api.max.ru/bot/{token}/setWebhook
{
  "url": "https://your-server.com/webhook"
}

Убедитесь, что ваш сервер отвечает на этот URL статусом 200 OK. MAX поддерживает только HTTPS (SSL-сертификат обязателен). Можно использовать Let's Encrypt или сервисы типа ngrok для тестирования.

Проверка webhook

После установки отправьте тестовый запрос через getWebhookInfo:

GET https://api.max.ru/bot/{token}/getWebhookInfo

В ответе вы увидите статус, количество ошибок и последнюю дату обновления.

Шаг 3: Обработка входящих данных

Когда пользователь пишет боту, MAX отправляет JSON-объект на ваш webhook. Пример структуры:

{
  "update_id": 12345,
  "message": {
    "chat": {"id": 67890, "type": "private"},
    "from": {"id": 111, "first_name": "Иван"},
    "text": "Привет"
  }
}

Ваш сервер должен распарсить этот JSON и выполнить нужную логику. Для ответа используйте метод sendMessage:

POST https://api.max.ru/bot/{token}/sendMessage
{
  "chat_id": 67890,
  "text": "Здравствуйте, Иван!"
}

Шаг 4: Добавление кнопок и клавиатур

Для удобства пользователей используйте интерактивные кнопки. В MAX поддерживаются:

• Reply-клавиатура — кнопки под полем ввода.
• Inline-кнопки — кнопки под сообщением (например, «Подробнее»).

Пример inline-кнопки:

{
  "chat_id": 67890,
  "text": "Выберите действие:",
  "reply_markup": {
    "inline_keyboard": [
      [{"text": "Каталог", "callback_data": "catalog"}],
      [{"text": "Контакты", "callback_data": "contacts"}]
    ]
  }
}

При нажатии пользователем на кнопку MAX пришлёт callback_query с вашими данными.

Шаг 5: Тестирование в песочнице

MAX предоставляет тестовую среду — Sandbox. Чтобы её активировать, в настройках бота включите «Режим разработчика». В этом режиме бот виден только вам и тестовым пользователям (добавьте их через «Тестовые аккаунты»). Отправляйте сообщения, проверяйте обработку ошибок, логируйте запросы.

Шаг 6: Публикация бота

После успешного тестирования отключите песочницу и отправьте бота на модерацию. Для этого в каталоге ботов нажмите «Опубликовать». Модераторы проверят соответствие правилам платформы (запрещены спам, мошенничество, NSFW-контент). Обычно проверка занимает 1–3 дня.

Интеграция с внешними сервисами

Бота можно связать с CRM, базой данных или платёжной системой через API. Например, для приёма заказов:

1. Пользователь отправляет команду /order.
2. Бот запрашивает данные (товар, адрес).
3. Сервер сохраняет заказ в БД и отправляет уведомление менеджеру.

Для платежей используйте API MAX Pay — бот может создавать счета и принимать оплату внутри чата.

Пример простого бота на Python

Для быстрого старта используйте библиотеку max-bot-api:

pip install max-bot-api

Код эхо-бота:

from max import Bot, Dispatcher, types

bot = Bot(token="YOUR_TOKEN")
dp = Dispatcher(bot)

@dp.message_handler()
async def echo(message: types.Message):
    await message.answer(f"Вы написали: {message.text}")

if __name__ == "__main__":
    dp.run_polling()

Запустите скрипт — бот будет отвечать на любое сообщение.

Частые ошибки и их решение

• Ошибка 401 Unauthorized — неверный токен. Проверьте, что токен скопирован без лишних пробелов.
• Webhook не отвечает — сервер недоступен или не принимает POST-запросы. Проверьте логи сервера.
• Бот не видит сообщения — возможно, webhook не установлен или указан неверный URL. Вызовите getWebhookInfo.
• Кнопки не работают — убедитесь, что callback_data не превышает 64 символа, а текст кнопки — 128.

Теперь вы знаете, как подключить бота в MAX. Начните с простого эхо-бота, постепенно добавляя функции. Документация API доступна на официальном сайте разработчиков. Удачи!