MAX Bot API меняется 19 июля 2026: как перевести бота на platform-api2.max.ru

Если у вас уже работает MAX-бот для заявок, поддержки, записи или уведомлений, его нужно проверить до 19 июля 2026 года. В документации MAX появилось критичное изменение: запросы к старому домену platform-api.max.ru нужно перевести на platform-api2.max.ru, а токен больше нельзя передавать в query-параметрах.

Коротко: рабочий MAX-бот после 19 июля может начать падать не из-за бизнес-логики, а из-за транспорта. Самые частые причины - старый API-домен, токен в URL, неподдерживаемый сертификат Webhook-endpoint, зависимость от GET /chats и Long Polling в production.

Если бот связан с лидами, CRM или поддержкой клиентов, откладывать проверку опасно: сбой будет выглядеть как "бот молчит", "сообщения не уходят", "webhook не приходит" или "чаты пропали".

Что именно меняется в MAX Bot API

На 16 июля 2026 года в официальной документации MAX указаны четыре изменения, которые напрямую влияют на боевые интеграции:

• HTTP-запросы нужно направлять на https://platform-api2.max.ru.
• Токен нужно передавать через заголовок Authorization: <token>.
• Для Webhook больше нельзя полагаться на HTTP и самоподписанные сертификаты.
• Метод GET /chats с июня 2026 больше не поддерживается.

Отдельно MAX рекомендует использовать Webhook для production-окружения. Long Polling остаётся удобным для разработки и тестирования, но для боевого бота это слабое место: есть ограничения по скорости и хранению событий.

Быстрый чек-лист миграции

Проверьте бота по этому списку. Если хотя бы один пункт не выполнен, есть риск, что интеграция отвалится или начнёт терять события.

1. В коде нет обращений к platform-api.max.ru.
2. Все API-запросы идут на https://platform-api2.max.ru.
3. Токен не передаётся как ?access_token=..., ?token=... или похожий query-параметр.
4. Во всех запросах есть заголовок Authorization: {access_token}.
5. Webhook доступен по HTTPS на порту 443.
6. Сертификат endpoint выдан доверенным центром или сертификатом Минцифры.
7. Сервер отдаёт полную цепочку сертификатов.
8. Webhook отвечает 200 OK быстрее чем за 30 секунд.
9. В подписке используется secret, а сервер проверяет X-Max-Bot-Api-Secret.
10. Логика получения chat_id не зависит от GET /chats.
11. Для чатов и каналов chat_id сохраняется из событий bot_added, bot_started и других webhook-событий.
12. Есть очередь или журнал повторной обработки, если CRM, ERP или база временно недоступны.

Для бизнеса главный вопрос простой: если бот принимает заявки, можно ли доказать, что после сбоя ни один лид не потеряется? Если нет, миграция должна включать не только замену URL, но и аудит архитектуры.

Как было раньше и как должно быть теперь

Плохой вариант - токен в URL:

curl -X POST "https://platform-api.max.ru/messages?user_id=123&access_token=TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Проверка связи"}'

Рабочий вариант после миграции - новый домен и Authorization header:

curl -X POST "https://platform-api2.max.ru/messages?user_id=123" \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Проверка связи"}'

Если в проекте есть SDK, wrapper-класс или общий API-клиент, начните с него. В хорошей архитектуре домен и способ авторизации меняются в одном месте. Если URL размазан по контроллерам, воркерам и cron-задачам, сначала стоит собрать единый клиент для MAX API.

Что проверить в Webhook

Webhook - это не просто URL в настройках. MAX валидирует TLS и ждёт быстрый успешный ответ от вашего endpoint. Поэтому проверка должна идти не только по коду, но и по инфраструктуре.

Минимальный production endpoint:

https://your-domain.ru/webhook

Что важно:

• только HTTPS;
• порт 443;
• домен в URL совпадает с CN или SAN сертификата;
• сервер отдаёт полную цепочку сертификатов;
• endpoint отвечает 200 OK в пределах 30 секунд;
• тяжёлая бизнес-логика не выполняется внутри webhook-контроллера.

Правильный паттерн для production:

1. Webhook принимает событие.
2. Проверяет X-Max-Bot-Api-Secret.
3. Кладёт событие в очередь или журнал.
4. Быстро возвращает 200 OK.
5. Отдельный worker обрабатывает событие, ходит в CRM, ERP, LLM или базу.

Такой подход защищает бота от каскадных отказов. Если CRM временно отвечает 502, webhook всё равно принимает событие, а worker повторит обработку позже.

Как обновить подписку через POST /subscriptions

Для production MAX рекомендует Webhook. Подписка создаётся через POST /subscriptions.

Пример:

curl -X POST "https://platform-api2.max.ru/subscriptions" \
  -H "Authorization: TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.ru/webhook",
    "update_types": ["message_created", "message_callback", "bot_started"],
    "secret": "your_secret"
  }'

secret лучше задавать всегда. Тогда каждый webhook-запрос можно проверять по заголовку X-Max-Bot-Api-Secret, а не принимать любые POST-запросы из интернета.

Если бот обрабатывает персональные данные, заявки, номера телефонов или статусы заказов, отсутствие проверки secret - это уже не техническая мелочь, а риск безопасности.

Что делать с GET /chats

С июня 2026 GET /chats больше не поддерживается. Если бот раньше периодически получал список чатов через этот метод, такую логику нужно заменить.

Новая схема:

1. Подписаться на события через POST /subscriptions.
2. Получать chat_id из событий, например bot_added или bot_started.
3. Сохранять chat_id в своей базе.
4. Обновлять хранилище при добавлении, повторном событии или удалении бота из чата.
5. Использовать сохранённый chat_id для отправки сообщений и других API-вызовов.

Важно: теперь поддержка списка чатов становится ответственностью вашей системы. Нужно предусмотреть дедупликацию, обработку повторных webhook-событий и удаление неактуальных chat_id.

Почему Long Polling лучше убрать из production

Long Polling выглядит проще: сервер сам ходит за событиями, не нужно открывать endpoint наружу. Но для production это плохой компромисс.

Риски Long Polling:

• ограничения по скорости получения событий;
• риск потерять контекст при неправильной работе с marker;
• сложное горизонтальное масштабирование;
• конфликт с активной webhook-подпиской;
• слабая наблюдаемость при сбоях.

Для тестового бота Long Polling нормален. Для бота, который принимает лиды, брони, обращения в поддержку или статусы заказов, лучше переходить на Webhook с очередью, логами и ретраями.

Подробнее архитектурную разницу мы разбирали в статье Webhook vs Long Polling в Production.

Типовые симптомы после неудачной миграции

Если после 19 июля бот начал вести себя нестабильно, проверьте эти признаки:

Симптом	Вероятная причина
401 Unauthorized	Токен всё ещё передаётся в URL или не уходит в Authorization
404 или сетевые ошибки	В коде остался старый домен platform-api.max.ru
Webhook не получает события	TLS, порт 443, цепочка сертификатов или неверный URL подписки
События приходят повторно	Нет идемпотентности по update_id или message_id
Чаты "исчезли"	Код зависел от GET /chats
Бот отвечает с задержкой	В webhook-контроллере выполняется тяжёлая CRM/LLM-логика
Лиды не попадают в CRM	Нет очереди и retry-механизма при сбое внешнего API

Самая неприятная ошибка - когда webhook отвечает 200 OK, но бизнес-процесс внутри уже сломан. Поэтому кроме uptime сервера нужно смотреть очередь событий, ошибки CRM, DLQ, время обработки и число неотправленных сообщений.

Мини-план миграции за один день

Если времени мало, идите по такому сценарию:

1. Найдите старый домен

По проекту нужно найти все вхождения:

platform-api.max.ru
access_token=
token=
/chats
/updates

Проверять надо не только приложение, но и cron-скрипты, worker-процессы, переменные окружения, CI/CD, документацию поддержки и старые SDK-конфиги.

2. Обновите общий API-клиент

Вынесите базовый URL и авторизацию в один модуль:

const MAX_API_BASE_URL = "https://platform-api2.max.ru";

async function maxApi(path, options = {}) {
  return fetch(`${MAX_API_BASE_URL}${path}`, {
    ...options,
    headers: {
      Authorization: process.env.MAX_BOT_TOKEN,
      "Content-Type": "application/json",
      ...(options.headers || {}),
    },
  });
}

Это упрощённый пример. В боевом коде добавьте таймауты, логирование, обработку 429, ретраи и маскирование токена в логах.

3. Пересоздайте или обновите Webhook-подписку

Создайте подписку на новый endpoint через POST /subscriptions, укажите нужные события и secret. После этого проверьте, что webhook реально получает тестовое событие и что заголовок X-Max-Bot-Api-Secret проверяется на вашей стороне.

4. Уберите зависимость от GET /chats

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

• chat_id;
• тип события, из которого он получен;
• дата первого получения;
• дата последнего подтверждения;
• статус активности;
• служебные метаданные.

5. Проведите дымовой тест

Минимальный набор проверок:

1. Пользователь пишет боту.
2. Webhook получает событие.
3. Сервер валидирует secret.
4. Событие сохраняется в очередь или журнал.
5. Worker обрабатывает событие.
6. Бот отправляет ответ через platform-api2.max.ru.
7. Если есть CRM, создаётся тестовый лид.
8. В логах нет токена в открытом виде.

Что это значит для бизнеса

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

Пользователь -> MAX -> Webhook -> очередь -> обработчик -> CRM/ERP -> ответ пользователю

Слабое место на любом участке может привести к потерянным заявкам. Особенно если бот:

• принимает обращения из рекламы;
• записывает клиентов на услуги;
• создаёт сделки в Bitrix24 или amoCRM;
• отдаёт статусы заказов;
• работает как первая линия поддержки;
• использует AI/RAG для ответов по базе знаний.

Если у вас уже есть такой бот, разумный минимум - технический аудит перед 19 июля и мониторинг в первые дни после миграции.

Когда стоит перепроектировать бота, а не только мигрировать API

Простой search-and-replace домена подходит только маленьким ботам без интеграций. Если бот связан с CRM, оплатами, заказами или персональными данными, лучше сразу проверить архитектуру.

Красные флаги:

• нет единого API-клиента MAX;
• токен хранится в коде;
• webhook пишет напрямую в CRM без очереди;
• нет идемпотентности;
• нет retry/backoff;
• нет DLQ;
• ошибки видны только в консоли;
• невозможно быстро понять, сколько событий потеряно;
• нет тестового контура.

В таких случаях миграция на platform-api2.max.ru - хороший повод привести бота к production-уровню. Для этого обычно нужны API-клиент, очередь, мониторинг, логирование, таблица событий, контроль дублей и понятный runbook для поддержки.

Внутренняя перелинковка по теме

Если вы только планируете запуск, начните с гайда как создать бота в MAX: требования бизнеса, безопасность и архитектура.

Если бот должен выдерживать нагрузку, полезен разбор лимитов API MAX и архитектуры highload-ботов.

Если нужно выбрать бизнес-сценарий, посмотрите типовые сценарии MAX-ботов: лидогенерация, поддержка и запись.

Если нужен аудит или разработка production-бота под продажи, поддержку и CRM, профильная услуга здесь: разработка MAX-ботов.

FAQ

Что нужно сделать до 19 июля 2026? Перевести запросы MAX API на platform-api2.max.ru, передавать токен через Authorization, проверить TLS/сертификаты Webhook-endpoint и убрать зависимость от GET /chats.

Можно ли оставить Long Polling? Для разработки и тестов - да. Для production MAX рекомендует Webhook, потому что Long Polling ограничен по скорости и сроку хранения событий.

Почему MAX-бот может перестать отвечать? Чаще всего из-за старого домена API, неправильной авторизации, проблем с TLS у webhook, неподдерживаемого GET /chats или отсутствия обработки повторных событий.

Нужно ли менять бизнес-логику бота? Не всегда. Но если бот пишет в CRM, принимает заявки или работает с заказами, миграцию лучше совместить с проверкой очередей, ретраев, идемпотентности и мониторинга.

Как понять, что миграция прошла успешно? Проведите тест: пользователь пишет боту, webhook получает событие, сервер проверяет secret, worker обрабатывает задачу, бот отвечает через platform-api2.max.ru, а CRM получает тестовую запись без ошибок.

Источники

• MAX API: общее описание
• MAX API: история изменений
• MAX API: POST /subscriptions
• MAX API: POST /messages
• MAX API: GET /updates
• MAX API: GET /chats