MAX Bot API и Telegram Bot API: чем отличаются
MAX Bot API устроен похоже на Telegram Bot API: бот отправляет HTTP-запросы, получает события через вебхук или long polling, отвечает сообщениями с кнопками. Но детали отличаются, и именно на них уходит время при переносе. Ниже сравнение по документации dev.max.ru и открытой OpenAPI-схеме MAX.
Адрес и авторизация
| Telegram | MAX | |
|---|---|---|
| Адрес API | api.telegram.org/bot<token>/<method> | platform-api2.max.ru/<resource> |
| Токен | В адресе запроса | В заголовке Authorization |
| Стиль методов | Один метод на действие: sendMessage | REST: POST /messages, PUT /messages |
| Сертификат | Стандартные центры | Цепочка Минцифры, её нужно добавить в доверенные |
Сообщения
| Telegram | MAX | |
|---|---|---|
| Длина текста | 4 096 символов | 4 000 символов |
| Форматирование | MarkdownV2, HTML | Markdown, HTML |
| Ответ на сообщение | reply_parameters | link с типом reply |
| Пересылка | forwardMessage | link с типом forward |
| Без звука | disable_notification | notify: false |
| Спойлеры, свои эмодзи | Есть | Нет |
Кнопки
В MAX только inline-клавиатура под сообщением: до 210 кнопок, до 30 рядов, до 7 кнопок в ряду. Кнопок link, open_app, request_contact и request_geo_location — не больше трёх в ряду. Подробнее о типах кнопок — в статье Кнопки в боте MAX.
| Telegram | MAX |
|---|---|
callback_data, до 64 байт | callback, payload до 1 024 символов |
url | link, до 2 048 символов |
web_app | open_app |
copy_text | clipboard |
Обычная клавиатура KeyboardButton | Нет, замена — кнопка message |
request_contact, request_location | request_contact, request_geo_location |
switch_inline_query, pay | Нет |
События
В Telegram все события приходят как Update с разными полями. В MAX у каждого события свой тип update_type.
| Telegram Update | MAX update_type |
|---|---|
message | message_created |
edited_message | message_edited |
callback_query | message_callback |
/start с меткой | bot_started с payload до 128 символов |
my_chat_member | bot_added, bot_removed, bot_stopped, bot_admin_permissions_changed |
chat_member | user_added, user_removed |
inline_query, poll, message_reaction | Нет |
Файлы
В MAX файл сначала загружается через POST /uploads, потом его токен прикрепляется к сообщению. Лимиты на загрузку: изображение до 50 МБ, видео до 250 МБ, аудио до 256 МБ, файл до 4 ГБ. Аудио, файл, контакт и стикер должны быть единственным вложением в сообщении, а фото и видео можно отправлять альбомом.
Вебхук и long polling
Оба способа есть: POST /subscriptions для вебхука и GET /updates для long polling. Но в бою MAX требует вебхук на HTTPS с портом 443, и пока подписка активна, long polling молча ничего не получает. Подробно — в статье Вебхук для бота в MAX.
Чего в MAX нет совсем
| В Telegram | Что делать | Как |
|---|---|---|
| Клавиатура под полем ввода | Покажет те же кнопки под сообщением. Нажатие отправит боту тот же текст, как в Telegram | Аналог |
| Опросы | Соберёт опрос на кнопках, сам посчитает голоса и обновит результат | Аналог |
| GIF, голосовые, кружки | Отправит как видео и аудио | Аналог |
| Спойлеры и свои эмодзи | Покажет как обычный текст | Аналог |
| Реакции и кубик | Пропустит. Бот получит ok: true и не упадёт | Пропуск |
| Стикеры из Telegram | Пропустит или заменит на эмодзи, который вы выберете | Пропуск |
| Темы в группах | Отправит сообщение в общий чат | Пропуск |
| Inline-режим, игры, звёзды | Вернёт понятную ошибку в формате Telegram | Ошибка |
| Платежи | Переделаем на оплату по ссылке через вашу платёжную систему, например ЮKassa или CloudPayments | Под ключ |
| Мини-приложения | Кнопка откроет приложение. Само приложение адаптируем под MAX | Под ключ |
Шлюз BotHop закрывает эти различия: бот говорит на Telegram Bot API, а шлюз переводит всё в MAX. Для бота меняется только адрес API, api.bothop.ru вместо api.telegram.org.
Частые вопросы
Какой адрес у MAX Bot API?
Документация MAX рекомендует `platform-api2.max.ru`. Токен передаётся в заголовке `Authorization`, а не в адресе запроса.
Какой лимит на длину сообщения в MAX?
4 000 символов. В Telegram — 4 096.
Есть ли в MAX обычная клавиатура под полем ввода?
Нет, только inline-клавиатура под сообщением. Её кнопка типа message отправляет боту текст, поэтому обычную клавиатуру можно заменить ею.