Чат-бот MAX: архитектура API, лимиты и 5 шагов к интеграции с CRM
Официальный чат-бот MAX функционирует на базе REST-архитектуры и предоставляет бизнесу бесплатный программный интерфейс для обработки входящих обращений. Платформа требует жесткого соблюдения серверных тайм-аутов при доставке событий и полностью исключает исходящие рассылки по холодным базам номеров. Разбираем технологический стек мессенджера, скрытые лимиты антиспам-системы и экономику внедрения корпоративных решений.
Технологический стек и доставка событий через Webhooks
Программный интерфейс MAX Bot API унифицирован под стандарты современных веб-сервисов и размещен на эндпоинте platform-api2.max.ru. Разработчикам доступны официальные пакеты SDK для окружения JavaScript/TypeScript (@maxhub/max-bot-api), а также сторонние библиотеки для Python и Go. Интегрируя чат-бот в MAX, HTTPS-запросы к платформе необходимо снабжать токеном авторизации, который передается исключительно в заголовке Authorization, а не в параметрах URL.
Механизм доставки данных Long Polling (/updates) предназначен только для этапа тестирования. В production-окружении архитектура мессенджера требует использования входящих вебхуков (Webhooks), что накладывает жесткие рамки на серверную сторону интегратора. При отправке вебхука эндпоинт вашей CRM-системы обязан вернуть ответ с HTTP-кодом 200 OK в течение интервала тайм-аута — 30 секунд. Возврат кодов ошибок или превышение временного порога считается платформой сбоем доставки. В таком случае мессенджер выполняет до 10 повторных запросов с экспоненциальной прогрессией задержки: первая попытка происходит через 60 секунд, вторая — через 150 секунд, третья — через 375 секунд и так далее.
Регистрация юрлица и модерация на портале разработчиков
Подключение официальных аккаунтов для бизнеса осуществляется через портал business.max.ru или сервисного бота @MasterBot. Запуск доступен только верифицированным юридическим лицам, индивидуальным предпринимателям и самозанятым. Регистрируя для площадки max ru чат-бот, вы проходите обязательную модерацию торговой марки.
Ранее системные юзернеймы формировались исключительно с привязкой к техническим идентификаторам организации (по шаблону idИНН_bot). Сейчас платформа развернула обновления Bot API, направленные на введение буквенных псевдонимов после расширенной проверки бренда. Масштаб архитектуры и ее готовность к высоким нагрузкам подтверждается окончательным переводом школьного сегмента платформы «Сферум» на серверные мощности MAX с интеграцией сервисов электронных дневников.
Чек-лист: 5 требований к инфраструктуре перед запуском
Планируя в MAX создание бота, передайте техническому отделу или интегратору этот список требований. Без их реализации стабильная работа API невозможна.
- Маршрутизация медиафайлов. При передаче тяжелых медиафайлов API переводит файл в промежуточный статус attachment.not.ready. Ваша система обязана иметь логику отложенного опроса серверов платформы для скачивания контента после завершения обработки.
- Ограничение частоты запросов (Rate Limit). На стороне CRM должен быть внедрен балансировщик, не допускающий отправку более 2 сообщений в секунду на один диалог.
- Асинхронная обработка вебхуков. Эндпоинт обязан отдавать HTTP 200 OK мгновенно, а саму бизнес-логику (поиск клиента в базе, создание сделки) выносить в фоновую очередь (Redis/RabbitMQ), чтобы уложиться в 30-секундный лимит.
- Идентификация пользователей. Логика рассылок должна опираться на внутренние идентификаторы user_id, а не на номера телефонов.
- Поддержка Model Context Protocol. Если вы планируете передавать управление диалогами внешним AI-агентам, сервер должен поддерживать стандарт MCP для корректного чтения контекста переписки.
Почему нельзя запустить холодную рассылку по номерам
Анализ практики внедрения выявил типовое заблуждение среди руководителей отделов продаж: компания рассчитывает загрузить купленную базу мобильных телефонов и запустить по ней исходящий прогрев. Интегрированные в мессенджер MAX чат-боты функционируют строго во входящем режиме.
Отправить сообщение абоненту первым по номеру телефона через официальный Bot API технически невозможно. Архитектура оперирует исключительно внутренними идентификаторами (user_id), требуя первичного триггера от самого пользователя — нажатия кнопки «Начать» или отправки текстового запроса. Кроме того, существует недетерминированность антиспам-политики для «серых» номерных подключений: если лимиты отправки пакетов для официального Bot API жестко зафиксированы в документации, то регламенты антиспам-фильтрации для обычных номеров публично не раскрываются, что делает партизанский маркетинг непредсказуемым.
Экономика внедрения и возможности Mini Apps
Официальный Bot API бесплатен со стороны оператора ООО «МАХ». Платформа не взимает абонентской платы за подключение, открытие диалоговых сессий или обработку неограниченного потока входящих текстовых пакетов. Бюджет коммерческого использования складывается из стоимости лицензий на коннекторы сторонних интеграторов (таких как Radist, Wazzup, Chat2Desk), расходов на техническое обслуживание серверов и бюджетов на таргетированную рекламу для привлечения пользователей.
Возможности API значительно расширены поддержкой интерактивных мини-приложений (Mini Apps) и веб-виджетов. Это позволяет разворачивать полноценные витрины интернет-магазинов и финансовые сервисы прямо внутри диалогового окна. В связке с Системой быстрых платежей (СБП) клиент проходит весь путь от квалификации заявки до оплаты, не покидая мессенджер.
Таблица: что чаще всего идет не так при интеграции
| Симптом в отделе продаж | Техническая причина | Что делать интегратору |
|---|---|---|
| Бот отправляет одно и то же сообщение клиенту несколько раз подряд | CRM отвечает на вебхук дольше 30 секунд или возвращает ошибку. Срабатывает экспоненциальный повтор платформы | Настроить асинхронную обработку: мгновенно отдавать 200 OK, а формирование ответа выносить в фоновый процесс |
| Клиент отправил видео, но в CRM пришло пустое сообщение или ошибка | Файл попал в статус `attachment.not.ready` | Внедрить логику отложенного поллинга: проверять статус файла через API каждые 5 секунд до готовности |
| Менеджер не может написать клиенту первым из интерфейса CRM | Попытка инициировать диалог по номеру телефона, что запрещено архитектурой Bot API | Запускать медийный трафик на ссылку бота или использовать веб-виджет на сайте для сбора первичных `user_id` |
| Аккаунт внезапно заблокирован за спам в разгар рекламной кампании | Превышен лимит Bot API (2 сообщения в секунду) или нарушены скрытые лимиты номерных подключений | Реализовать Rate Limiter на сервере отправки, жестко дросселирующий исходящую очередь сообщений |
Что НЕ помогает: попытки переключить production-сервер с Webhooks на метод Long Polling ради обхода 30-секундных тайм-аутов. Платформа принудительно требует использования вебхуков для верифицированных бизнес-аккаунтов при высоких нагрузках.
Что делать дальше
Сначала проведите аудит текущей инфраструктуры: убедитесь, что ваша CRM умеет асинхронно обрабатывать вебхуки и имеет готовые сценарии для работы со статусом attachment.not.ready. Затем подготовьте учредительные документы и пройдите верификацию юридического лица на портале business.max.ru для резервирования буквенного алиаса бренда. Если вы хотите интегрировать мессенджер в сложные процессы без написания промежуточных серверов с нуля, мы помогаем настроить бесшовную передачу данных между MAX и вашей учетной системой с соблюдением всех лимитов платформы.
Частые вопросы
Взимает ли мессенджер плату за каждое отправленное сообщение?
Нет, официальный Bot API мессенджера полностью бесплатен со стороны оператора ООО «МАХ». Вы платите только за сторонние сервисы интеграции и свои серверы.
Можно ли собрать бота для MAX без навыков программирования?
Да, в экосистему интегрировано более 15 визуальных конструкторов (SaleBot, Watbot, Aimylogic и другие), которые позволяют перенести логику из других мессенджеров без написания кода.
Как принять оплату от клиента прямо в чате?
Через технологию Mini Apps. Она позволяет открыть внутри мессенджера веб-витрину и провести транзакцию через Систему быстрых платежей (СБП).
Разрешено ли ботам автоматически добавлять пользователей в группы?
С сентября 2026 года прямое добавление участников в чаты через метод POST /chats/{chatId}/members жестко ограничено политикой платформы.
Как отправить клиенту рассылку по базе номеров?
Через официальный Bot API — никак. Он работает только по внутренним идентификаторам (user_id) и требует, чтобы клиент первым нажал кнопку «Начать».