Genius-bot · 8 минут чтения
MAX боты через API работают примерно так же, как боты в Телеграме: сайт или сервер отправляет HTTPS-запрос с токеном, и бот присылает сообщение в нужный чат. Ниже разберём, как устроен API ботов MAX: адрес сервера, авторизация, отправка сообщений, получение обновлений и лимиты. В конце покажем, как подключить бота к сайту на WordPress без единой строки кода.
Что такое API ботов MAX и зачем он сайту
API ботов MAX — это набор HTTP-методов, через которые программа управляет ботом: отправляет сообщения, читает входящие, редактирует и удаляет их, работает с чатами и каналами. Ответы приходят в формате JSON, все строки в кодировке UTF-8, а даты передаются в миллисекундах с 1 января 1970 года (UTC).
Для владельца сайта самый частый сценарий простой: бот для мессенджера MAX присылает уведомление о новой заявке или заказе менеджеру или в рабочий чат. Для этого хватает двух-трёх методов из всего API. Боты умеют и больше: отвечать на вопросы, показывать кнопки, запрашивать у пользователя контакт или геолокацию, открывать мини-приложения.
Если вы уже работали с Телеграмом, отличий немного, но они важны. В Telegram Bot API токен вставляется прямо в адрес запроса, а MAX боты API принимают токен только в заголовке. Лимит текста в Телеграме — 4096 символов, в MAX — 4000. Создать бота в Телеграме может любой пользователь через @BotFather, а в MAX — только проверенный бизнес. Как настраивается Телеграм, мы разобрали в статье телеграм-бот для уведомлений с сайта.
Официальное описание лежит на портале dev.max.ru, а полная спецификация OpenAPI в формате YAML — в репозитории max-messenger/api-schema на GitHub. Там же есть официальные библиотеки для TypeScript/JavaScript, Go и Python.
Кто может создать бота и получить токен
Создавать ботов и работать с API MAX сейчас могут только юрлица, ИП и самозанятые — резиденты России. Частному лицу без статуса бота не зарегистрировать: личный аккаунт в мессенджере для этого не подходит.
Порядок такой:
- Подключиться к платформе MAX для партнёров (business.max.ru) и создать профиль организации, ИП или самозанятого.
- Дождаться верификации профиля.
- Создать бота в разделе «Чат-боты» и дождаться модерации.
- После модерации взять токен в настройках бота.
Подробная инструкция с разбором ошибок — в статье как получить токен для бота в MAX. Здесь важно запомнить одно: токен — это ключ к управлению ботом. Кто его знает, тот может писать от имени бота.
Базовые правила API: адрес, токен, формат
Все запросы идут на один домен. Раньше использовался platform-api.max.ru, сейчас документация требует обращаться к platform-api2.max.ru. Токен передаётся только в заголовке, передача через параметр в адресе больше не поддерживается.
| Параметр | Значение |
|---|---|
| Базовый адрес | https://platform-api2.max.ru |
| Авторизация | Заголовок Authorization: ВАШ_ТОКЕН, без слова Bearer |
| Формат данных | JSON, UTF-8 |
| Методы HTTP | GET — получить, POST — создать, PUT — изменить, DELETE — удалить, PATCH — исправить |
| Длина текста сообщения | До 4000 символов |
| Разметка текста | Поле format: markdown или html |
| Сертификат | Домен подписан корневым сертификатом Минцифры, его нужно добавить в доверенные |
Проверить, что токен рабочий, проще всего запросом информации о боте:
curl -X GET "https://platform-api2.max.ru/me" -H "Authorization: ВАШ_ТОКЕН"
В ответ придёт JSON с полями user_id, name, username и is_bot: true. Если вместо этого пришёл код 401 — токен неверный или скопирован с лишним пробелом.
Как отправить сообщение: метод POST /messages
Отправка — главный метод для уведомлений. Получатель указывается в адресе запроса, а не в теле:
?chat_id=…— если пишете в чат или канал;?user_id=…— если пишете конкретному пользователю.
В теле передаётся объект сообщения: текст, при желании формат разметки, вложения и кнопки. Пример на curl:
curl -X POST "https://platform-api2.max.ru/messages?chat_id=ВАШ_CHAT_ID" -H "Authorization: ВАШ_ТОКЕН" -H "Content-Type: application/json" -d '{"text":"Новая заявка с сайта: Иван, +7 900 000-00-00"}'
Тот же запрос из WordPress через встроенную функцию wp_remote_post:
$response = wp_remote_post( 'https://platform-api2.max.ru/messages?chat_id=ВАШ_CHAT_ID', array( 'headers' => array( 'Authorization' => 'ВАШ_ТОКЕН', 'Content-Type' => 'application/json' ), 'body' => wp_json_encode( array( 'text' => 'Новая заявка с сайта' ) ), 'timeout' => 15 ) );
Полезные детали из спецификации:
- поле
notify: falseотправляет сообщение без уведомления участникам чата (в канале с таким значением метод вернёт ошибку); - параметр
disable_link_previewв адресе управляет превью ссылок; - при
"format": "html"поддерживаются только базовые теги: жирный, курсив, зачёркнутый, подчёркнутый, ссылка, моноширинный текст, цитата, заголовок; остальные теги вырезаются; - кнопки добавляются вложением типа
inline_keyboard, например кнопка-ссылка на заказ в админке.
Если ответ пришёл с кодом 200, в нём будет созданное сообщение с его идентификатором.
Как получать обновления: Long Polling и Webhook
Чтобы бот узнавал о входящих сообщениях и событиях, у API есть два способа. Использовать их одновременно нельзя — нужно выбрать один.
Long Polling: GET /updates
Ваш скрипт сам спрашивает сервер, что нового. Работает сразу после создания бота, удобно для тестов и для поиска chat ID:
curl "https://platform-api2.max.ru/updates?limit=10&timeout=30" -H "Authorization: ВАШ_ТОКЕН"
Параметры: limit — от 1 до 1000 (по умолчанию 100), timeout — от 0 до 90 секунд (по умолчанию 30), marker — номер следующего обновления, types — список нужных типов через запятую, например message_created,bot_started. Документация предупреждает: этот способ ограничен по скорости и сроку хранения событий и не подходит для рабочего режима.
Webhook: POST /subscriptions
Вы сообщаете MAX адрес своего сервера, и события приходят туда сами. Для рабочего бота это рекомендуемый способ. Требования: только HTTPS на порту 443, сертификат от доверенного центра (самоподписанные и HTTP не принимаются с 25 мая 2026 года), ответ сервера — код 200. Если сервер недоступен, MAX повторяет доставку с растущими интервалами, но не дольше примерно 8 часов.
Для уведомлений с сайта обновления вообще не нужны: сайт только отправляет сообщения. Получать события понадобится, если бот должен отвечать клиентам.
Лимиты и коды ошибок
Сводка по ограничениям, которые чаще всего встречаются при отправке уведомлений:
| Что | Ограничение или значение |
|---|---|
| Частота запросов к API | Не более 30 запросов в секунду |
| Минимальный интервал опроса /updates | 300 мс |
| Текст сообщения | До 4000 символов, считаются и пробелы, и символы разметки |
| Код 401 | Ошибка авторизации: неверный или отозванный токен |
| Код 403 | Нет доступа: пользователь остановил бота или бот не состоит в чате |
| Код 404 | Ресурс не найден, например неверный адрес метода |
| Код 429 | Превышено количество запросов |
| Код 503 | Сервис временно недоступен |
При ошибке сервер возвращает JSON с полями code (ключ ошибки) и message (описание). Отдельная проблема, которой нет в Телеграме, — сертификат. Если хостинг не доверяет корневому сертификату Минцифры, запрос из PHP упадёт с ошибкой SSL ещё до того, как дойдёт до API. Лечится добавлением сертификата в доверенные на сервере; отключать проверку SSL не стоит.
MAX боты API на сайте WordPress без кода
Писать запросы вручную имеет смысл, если у вас своё приложение. Для обычного сайта на WordPress проще поставить готовый плагин. Бесплатный плагин Pingtrix отправляет уведомления в Телеграм и MAX о новых заказах WooCommerce (и в классическом, и в блочном оформлении), смене статуса заказа, заявках из Contact Form 7, WPForms и Elementor Pro, комментариях на модерации, регистрациях и входе администратора.
Как подключить:
- Установите и активируйте Pingtrix в WordPress.
- Вставьте токен бота в настройках MAX в плагине.
- Напишите боту в MAX любое сообщение и воспользуйтесь кнопкой «Найти chat ID», чтобы не искать идентификатор вручную через API.
- Включите нужные события и при желании поправьте шаблоны сообщений с подстановками.
- Нажмите «Отправить тестовое сообщение» и проверьте, что оно пришло.
Под капотом плагин делает то же, что описано выше: POST /messages с токеном в заголовке. Отправка идёт в фоне через WP-Cron, поэтому посетитель не ждёт ответа мессенджера. Если отправка не удалась, плагин повторит её через минуту, а последние 50 отправок видны в журнале. Пароли, номера карт, CVV и капча из форм в сообщения не попадают. Если заказы должны уходить одному сотруднику, а заявки другому, пригодится версия Pingtrix Pro: получатели по событиям, кнопки «Открыть заказ» и тихие часы.
Частые вопросы
Нужен ли Bearer в заголовке Authorization?
Нет. MAX принимает токен в заголовке как есть, без префикса. Некоторые генераторы клиентов добавляют Bearer автоматически — это нужно отключать.
Можно ли передать токен в адресе запроса?
Нет, передача токена через параметр в URL больше не поддерживается. Только заголовок Authorization.
Чем отличается chat_id от user_id?
chat_id — идентификатор чата или канала, user_id — конкретного пользователя. Для отправки нужен один из них, оба указываются в адресе запроса POST /messages.
Сколько сообщений можно отправить в секунду?
Документация называет предел 30 запросов в секунду. Для уведомлений о заявках этого с запасом хватает даже очень загруженному магазину.
Работает ли старый адрес platform-api.max.ru?
Документация требует перейти на platform-api2.max.ru. На старый домен новые интеграции лучше не завязывать.
Вывод
API ботов MAX устроен просто: один домен, токен в заголовке, POST /messages для отправки и GET /updates или вебхук для входящих событий. Для своего приложения этого достаточно, чтобы собрать бота за вечер. Если нужно только получать заявки и заказы с сайта, проще поставить Pingtrix: токен, chat ID, тестовое сообщение — и уведомления уже идут в MAX и Телеграм.
