Подключение бота к API MAX: где теряется рабочий день
Бот «Формулы Ремонта» отвечает клиентам в MAX с весны. Подключали мы его сами, через API, и на старте потеряли рабочий день в трёх местах, о которых в документации ничего нет. Ниже эти места по порядку и то, как их обойти.
Зачем сервису бот в MAX
Логика та же, что с Авито и Telegram: клиент пишет в тот мессенджер, который у него открыт. Разница в том, что в MAX очередь из конкурентов ещё не выстроилась. Бот, который отвечает там первым, получает вопрос целиком. Без него человек напишет «здравствуйте» и уйдёт, не дождавшись.
Бот в MAX умеет то же, что в других каналах: принять первое сообщение, распознать модель и поломку, назвать цену из прайса, записать на диагностику, передать оператору сложный случай. Кнопки под сообщением там тоже есть, и форматирование текста работает.
Как это подключается
Схема стандартная: заводится бот, выдаётся токен, дальше сервер забирает сообщения длинным опросом и отвечает через API. Документация лежит на dev.max.ru. Как завести бота в кабинете и где взять токен, мы разобрали по шагам. Никаких вебхуков с белым IP на старте не нужно — long polling работает с обычного сервера.
Дальше начинается то, чего в документации нет.
Корневой сертификат: полдня на ровном месте
Первое соединение с API просто не поднимается. Выглядит это как сетевая проблема: таймауты, ошибка TLS, «не отвечает». Проверяются порты, фаервол, DNS, прокси — и всё в порядке.
Причина в другом: серверу не хватает корневого сертификата Минцифры (Russian Trusted Root CA) в хранилище доверенных корней. Ставится он двумя командами. Искали мы его полдня — обидно, потому что ошибка притворяется сетевой и уводит совсем не туда. На свежей виртуалке ставьте сертификат до первого запроса к API.
Адрес API переехал
Примеры кода полугодовой давности ведут на platform-api.max.ru. Рабочий адрес — platform-api2.max.ru: миграция прошла 24 июня 2026 года, старый хост отвечал до 19 июля, потом замолчал.
Ловушка простая. Старые примеры до сих пор первыми находятся в поиске, а код из них не падает с понятной ошибкой: он просто ничего не получает в ответ. Сначала проверьте адрес. Потом ищите баг у себя.
Картинка уходит не с первого раза
Файл, загруженный в MAX, обрабатывается на их стороне асинхронно. Если отправить сообщение с вложением сразу после загрузки, приходит ответ 400 с кодом attachment.not.ready.
Лечится повтором: пауза полторы секунды и та же отправка, до пяти попыток. Важно ретраить именно этот код, а не любую четырёхсотую ошибку, иначе бот будет молотить запросами по настоящим ошибкам вроде неверного chat_id. У нас это отдельная ветка в коде отправки, и с ней картинки в MAX уходят стабильно.
Чек-лист подключения
Порядок, который экономит тот самый рабочий день:
- Поставить корневой сертификат Минцифры на сервер и проверить, что запрос к API проходит из консоли.
- Проверить адрес:
platform-api2.max.ru, а не то, что нашлось в старых примерах. - Поднять длинный опрос и убедиться, что бот видит первое сообщение из тестового диалога.
- Прогнать отправку с картинкой и заложить ретрай на
attachment.not.ready. - Проверить кнопки и форматирование: в MAX они есть, но верстать сообщение приходится под них.
- Подключить тот же источник цен и правил, что у остальных каналов, чтобы ответы не разъезжались.
Последний пункт важнее, чем кажется. Бот, у которого в MAX свой прайс, а на Авито другой, рано или поздно назовёт клиенту две разные цены на один ремонт — и объясняться придётся администратору.
Что это даёт сервису
Свободный канал и та же логика ответов, что в Авито и Telegram: один прайс, одни правила, одна лента заявок. Клиент пишет из уже установленного мессенджера: MAX у части аудитории уже на телефоне, и таких телефонов с каждым месяцем больше.
Как это выглядит внутри и что бот отвечает клиентам — на главной странице ChatOffice. Про соседние каналы: чат-бот ВКонтакте для сервисного центра и чем сценарный бот отличается от бота на ИИ.