Bot API MAX: лимиты, разметка и подводные камни

Q: Работает ли получение списка чатов бота?

Да. GET /chats отдаёт все чаты и каналы, где состоит бот, — проверено 4 августа 2026 (встречающееся в статьях утверждение, что метод отключён, неверно). На нём удобно строить диагностику: видно, куда бота добавили и где не хватает прав.

Эта страница — не пересказ документации, а список того, обо что мы спотыкались, пока писали бота для каналов MAX. Всё проверено на боевом сервере 4–5 августа 2026. Там, где поведение нигде не описано, стоит пометка «намерено».

Точки входа

Хост	Для чего	Особенность
`botapi.max.ru`	Bot API для чат-ботов	обычный сертификат Let's Encrypt, TLS без сюрпризов
`platform-api2.max.ru`	платформенное API	требует корневой сертификат Минцифры в доверенных

Если вы пишете обычного бота, вам нужен первый. Второй хост без установленного российского корневого сертификата не поднимется по TLS вообще — с части хостингов он недоступен и с сертификатом.

Авторизация: токен без Bearer

Самая частая ошибка первого часа. Токен от MasterBot кладётся в заголовок Authorization сырым, без префикса Bearer:

Authorization: 0123abcd...           ← так
Authorization: Bearer 0123abcd...    ← 401

Токен выдаётся один раз и повторно не показывается. Храните его в переменной окружения, а не в коде.

Лимиты

Что	Значение	Источник
Запросов к API на бота	30 в секунду	намерено
Сообщений в один чат	2 в секунду	намерено
Длина текста сообщения	4000 символов	намерено

Практический вывод: массовую рассылку по сетке каналов нельзя гнать в один поток без пауз — упрётесь не в общий лимит, а в лимит на конкретный чат. Мы решаем это очередью с задержкой между отправками в один и тот же канал.

Разметка: MAX понимает HTML

При отправке сообщения указывается format: "html", после чего работают теги b, i, u, s, code, blockquote, a. Этого достаточно, чтобы перенести пост из Telegram без потери оформления.

Подводные камни разметки:

Смещения сущностей Telegram считаются в UTF-16. При конвертации entities → HTML позиции нужно переводить именно из UTF-16, иначе на каждом эмодзи разметка съезжает.
Не экранируйте содержимое href. html.escape по адресу превращает & в &, и партнёрские метки перестают работать.
Превью ссылки цепляется к последней ссылке в тексте. Если ссылок несколько, отправляйте с disable_link_preview, иначе под постом появится карточка случайного сайта.

Статистика: просмотры есть, но поштучно

GET /messages/{mid} возвращает stat.views и прямую ссылку на пост (url). Массовой выдачи охватов нет: чтобы построить отчёт за неделю, нужно обойти посты по одному и сложить.

Мы обходим опубликованные посты раз в час за последние 14 дней и складываем из этого среднее на пост, «просмотров на подписчика» и лучшие часы публикации. Заодно выяснилось, что показатель «просмотров на подписчика» бывает больше 100%: считаются все, кто открыл пост, а не только подписчики канала.

Реакций и репостов Bot API не отдаёт вовсе — если сервис показывает вам такой график по каналу MAX, он его либо считает сам по своим постам, либо рисует.

Чего в Bot API нет

Ограничения участника. Только удалить сообщение или назначить админа. «Мут» любого бота в MAX — это автоматическое удаление сообщений нарушителя.
Опросов. Такого типа вложения нет, кросспостинг опросов из Telegram невозможен.
Связи «канал → чат обсуждения». Поле не документировано; определять привязку приходится косвенно.
Реакций и репостов в статистике (см. выше).

Webhook или long polling

Работают оба режима, но держать их одновременно нельзя: включённый вебхук — и опрос обновлений больше не нужен. Для боевого бота берите вебхук: он экономит и запросы, и память на сервере. Требования обычные — HTTPS с валидным сертификатом и быстрый ответ; секрет удобно спрятать прямо в путь вебхука.

Обновления приходят и о служебных событиях: бот узнаёт, что его добавили в канал (bot_added) или что пользователь остановил диалог (bot_stopped). На первом строится автопривязка канала без ввода кодов, на втором — честная статистика активных пользователей.

Клиентские библиотеки

У платформы есть официальные клиенты (Go, TypeScript, Java) и активные сообщественные для Python и PHP. Если задача простая, HTTP-клиента с нуля хватает: методов немного, формат ответов предсказуемый.

Частые вопросы

Где взять токен бота MAX?

В самом мессенджере: у MasterBot создаётся новый бот, он же выдаёт персональный токен. Токен показывается один раз, восстановить его нельзя — только перевыпустить.

Работает ли получение списка чатов бота?

Да. GET /chats отдаёт все чаты и каналы, где состоит бот, — проверено 4 августа 2026 (встречающееся в статьях утверждение, что метод отключён, неверно). На нём удобно строить диагностику: видно, куда бота добавили и где не хватает прав.

Можно ли отправлять файлы и видео?

Да, вложения поддерживаются, включая крупные файлы. Практический совет: загружайте вложение заранее и переиспользуйте его идентификатор, если один и тот же файл уходит в несколько каналов.

Почему бот не может писать в канал, хотя он администратор?

Проверьте конкретное право «писать сообщения» — при добавлении администратора оно не всегда включено. Это отдельный переключатель, и без него отправка отвечает ошибкой прав, а не молча.

Чем Bot API MAX отличается от Bot API Telegram?

Идея та же — HTTP-методы и токен, — но детали расходятся. В MAX токен идёт в Authorization без Bearer, разметка передаётся HTML-тегами через format: "html", а не сущностями со смещениями. И главное: в MAX нет ограничения прав участника, нет опросов и нет массовой выдачи охватов. Переносить код из Telegram один в один не получится.

Есть ли лимит на число сообщений в сутки?

Суточного лимита мы не встречали — упирается всё в секундные: 30 запросов в секунду на бота и 2 сообщения в секунду в один чат. При рассылке по сетке каналов узкое место именно второе, поэтому отправку в один и тот же чат нужно разносить во времени.