DeveloctopusСтатья для тех, кто уже решил запускать бота в MAX и хочет понимать, что происходит внутри проекта. Разберём разработку MAX бота по шагам: из чего состоит архитектура, как бот получает события, где хранить состояние диалога и что проверить перед запуском.
Из чего состоит бот
Снаружи бот выглядит как собеседник в мессенджере. Внутри это обычное серверное приложение, которое общается с платформой MAX по HTTP API: получает события (новое сообщение, нажатие кнопки) и отправляет ответы. Документация API лежит на dev.max.ru, и любой проект стоит начинать с её актуальной версии.
Типичная архитектура выглядит так:
- Backend — сервер с логикой сценариев. Язык и фреймворк выбираются под команду, которая будет поддерживать проект: Node.js, Python, Go — для бота это не принципиально.
- Токен бота — секретный ключ, которым бот подтверждает свои запросы к API. Он хранится в переменных окружения или менеджере секретов, а не в коде и не в репозитории.
- База данных — пользователи, состояние диалогов, заявки, история. Чаще всего PostgreSQL.
- Интеграции — CRM, учётная система, платёжный сервис, почта.
- Админ-панель — интерфейс для сотрудников: заявки, тексты, рассылки, статистика.
Если токен утёк — например, его случайно выложили в открытый репозиторий, — его нужно сразу перевыпустить. Как именно это делается, уточняется по документации платформы, но сам принцип одинаков везде: токен равен полному доступу к боту.
Webhook или long polling
Получать события от MAX бот может двумя способами. При webhook платформа сама отправляет каждое событие на ваш адрес. При long polling бот периодически спрашивает у API, не появилось ли новых событий.
| Критерий | Webhook | Long polling |
|---|---|---|
| Как работает | Платформа присылает событие на ваш HTTPS-адрес | Бот сам запрашивает новые события у API |
| Что нужно | Публичный домен и HTTPS с валидным сертификатом | Только исходящий доступ в интернет |
| Где удобно | Рабочая среда, несколько серверов за балансировщиком | Локальная разработка, тесты, небольшие внутренние боты |
| Задержка | Минимальная | Небольшая, зависит от настроек опроса |
Для продакшена мы обычно выбираем webhook, а long polling оставляем для разработки: так программист может запускать бота у себя на ноутбуке без публичного адреса. Конкретные требования к адресу вебхука, портам и сертификатам уточняются по документации платформы.
Два правила, которые избавляют от половины проблем. Первое: обработчик вебхука должен отвечать быстро, а тяжёлую работу — запрос в CRM, генерацию документа — отправлять в очередь. Второе: обработка должна быть идемпотентной. Если событие по какой-то причине придёт повторно, бот не должен создать вторую заявку или списать оплату дважды.
Проектирование сценариев и кнопок
Код начинается после того, как сценарий нарисован. Сначала рисуется карта диалога: каждый шаг, что пишет бот, какие кнопки показывает, куда ведёт каждый вариант. На этом этапе видно, где сценарий слишком длинный, где пользователь может зайти в тупик и каких данных не хватает менеджеру.
Что стоит заложить в любой сценарий:
- Понятное главное меню и кнопку возврата в него из любого шага.
- Обработку свободного текста: человек не нажал кнопку, а написал вопрос. Бот должен ответить, а не молчать.
- Подтверждение перед отправкой заявки, чтобы можно было исправить ошибку.
- Сценарий «позвать человека» — передачу диалога сотруднику.
- Поведение при повторном входе: продолжить незаконченный диалог или начать заново.
Какие типы кнопок и клавиатур доступны в MAX, как они выглядят и сколько их можно показать в одном сообщении — проверяем по документации на момент разработки. Сценарий при этом лучше описывать в терминах «выбор из вариантов» и «ввод текста», а не привязывать к конкретному виду кнопки: так его проще перенести и в другой мессенджер.
Хранение состояния диалога
Бот должен помнить, на каком шаге находится каждый пользователь и что тот уже ответил. Самый простой вариант — держать это в памяти процесса — ломается при первом перезапуске сервера: все незаконченные диалоги теряются. А если серверов два, пользователь может попасть на тот, который о нём ничего не знает.
Поэтому состояние хранится во внешнем хранилище. Для короткоживущих данных шага подходит Redis, для всего, что важно бизнесу, — заявки, контакты, история обращений — основная база данных. Сценарий удобно описывать как конечный автомат: набор состояний и разрешённых переходов между ними. Такой код легче читать, тестировать и менять.
Отдельно продумайте брошенные диалоги. Например, человек начал заявку и пропал на три дня. Через сколько времени сбрасывать его состояние? Нужно ли напомнить ему о незаконченной заявке и разрешают ли это правила платформы? Эти решения лучше принять до разработки, а не после жалоб.
Админ-панель и логирование
Без админ-панели любое изменение текста превращается в задачу для программиста. Минимальный набор, который мы закладываем: список заявок с фильтрами и статусами, редактирование текстов и кнопок, просмотр диалога с конкретным пользователем, роли сотрудников. Если в сценарии есть рассылки — интерфейс для них с предпросмотром и тестовой отправкой.
Логирование нужно с первого дня. Записываем входящие события, исходящие сообщения, ошибки API и ошибки интеграций. На критичные ошибки — например, CRM не принимает заявки — настраиваем уведомления разработчику, чтобы узнать о проблеме раньше клиента.
Если бот собирает телефоны, имена или другие персональные данные, учитывайте требования 152-ФЗ: согласие на обработку, место хранения, срок хранения, доступы сотрудников. В логи не стоит писать персональные данные целиком — достаточно идентификатора пользователя.
Тестирование
- Автотесты на бизнес-логику: переходы сценария, расчёты, формирование заявки. Они не зависят от мессенджера и запускаются за секунды.
- Отдельный тестовый бот со своим токеном, подключённый к тестовой базе и тестовой CRM. Боевой бот для экспериментов не используем.
- Ручной прогон всех сценариев на разных устройствах — телефон и, если поддерживается, десктопная версия мессенджера.
- Проверка ошибок: что происходит, если CRM недоступна, пользователь отправил файл вместо текста, нажал старую кнопку из сообщения недельной давности.
- Нагрузочная проверка, если ожидаются пики — например, после массового уведомления или рекламной кампании.
На этом этапе заказчик тоже проходит сценарии сам. Сотрудники, которые будут работать с заявками, часто замечают то, что не видно разработчику: не хватает поля, неудобный порядок вопросов, непонятная формулировка.
Запуск и что после него
Перед запуском сверяемся с документацией ещё раз: как бот публикуется, есть ли проверка со стороны платформы, какие данные нужны для регистрации — всё это уточняется по документации платформы. Бот оформляется на аккаунт заказчика, чтобы доступы не зависели от подрядчика.
Дальше бот запускается сначала на небольшую часть аудитории или на сотрудников, затем на всех. Первые две недели смотрим на статистику: где пользователи бросают сценарий, какие вопросы бот не понимает, сколько заявок дошло до CRM. Обычно после этого есть пара правок — это нормальная часть процесса, а не признак плохой работы.
Если Telegram-бот у вас уже есть, разработка макс бота может пойти быстрее за счёт общего ядра — подробности в статье о переносе бота из Telegram в MAX. Про подключение CRM — в материале об интеграции с amoCRM и Битрикс24, а что входит в сопровождение после запуска — в статье о технической поддержке.
Частые вопросы
Сколько длится разработка бота для MAX?
Бот с одним-двумя сценариями и отправкой заявок в CRM можно запустить от двух недель. Если нужны админ-панель, оплата и несколько интеграций, срок считаем после брифа.
Сколько стоит разработка MAX-бота?
От 30 000 ₽ за бота с одним-двумя сценариями и отправкой заявок в CRM. Админ-панель, оплата и дополнительные интеграции увеличивают бюджет — точную сумму называем после бесплатного брифа.
Можно ли обойтись конструктором ботов?
Для простой анкеты — да, если конструктор поддерживает MAX. Когда нужны интеграции, сложная логика или контроль над данными, собственный backend обычно выходит надёжнее и дешевле в долгую.
Кому принадлежат код и бот после разработки?
Заказчику. Бот регистрируется на ваш аккаунт, код передаётся в ваш репозиторий вместе с инструкцией по развёртыванию.
Нужен ли отдельный сервер?
Да, боту нужно место, где работает backend. Подойдёт облачный сервер или контейнерная платформа; для вебхука понадобится домен с HTTPS.
Обсудим проект
Нужна похожая разработка?
Расскажите о задаче — уточним детали, предложим формат запуска и подготовим предварительную оценку. Это бесплатно.
Источники
Опубликовано · Обновлено