Адаптация Telegram-плагина под MAX

Название плагина	MAX, MAXmediaCommon.Integrations.Max
Разработчик	Официальные плагины от Metabot
Авторы	Борисов Павел (https://t.me/mr_result)Metabot
Дата создания	2505 МартаОктября 20252026
Последняя дата обновления	1705 АвгустаОктября 2026

Описание

ЭтотПлагин Max позволяет использовать один и тот же скрипт бота в Telegram и в мессенджере Max. Он не вводит новый класс: плагин предоставляет«патчит» удобныйметоды интерфейскласса дляTelegramMessage работыиз сплагина MAXCommon.Integrations.Telegram.

Если лид пришёл из Telegram — работают оригинальные методы Telegram-плагина (ничего не меняется). Если лид пришёл из Max — те же самые методы (`send`, edit, addReplyToText, removeInlineKeyboard, removeReplyKeyboard, getMessagePayload, `debug`) отправляют запросы в Max Bot API. Работает как доработка для плагина Telegram. Он

Плагин поддерживает отправку текстовых сообщений, фотографий, создание клавиатурinline-клавиатур, обработку нажатий кнопок и обработку ответов пользователя.пользователя, редактирование сообщений и отправку медиагрупп.

Документация Max Bot API: https://dev.max.ru/docs-api

Адаптация плагина в коде

Для работы плагина Telegram в MAX, после подключения основного класса TelegramMessage добавьте вызов сниппета Business.Integrations.MAX. Затем добавьте инициализацию плагина.

Сначала подключается Telegram-плагин, затем — Max-плагин. Порядок важен: Max-плагин патчит уже загруженный класс. Повторное подключение безопасно (патч ставится один раз).

let TelegramMessage = require('Common.Integrations.Telegram')
snippet('Business.Integrations.MAX')

let msg = new TelegramMessage()

По аналогии адаптируется плагин TelegramMedia.

let { TelegramMediaGroup } = require('Common.Integrations.TelegramMedia')
snippet('Business.Integrations.MAXmedia')

let mediaMsg = new TelegramMediaGroup()

Основные параметры

msg.text = "Ваше сообщение" // Текст сообщения
msg.parse_mode = "HTML" // Режим форматирования (HTML или MarkdownV2)
msg.protect_content = true // Защита контента от пересылкиMarkdown)
msg.keyboard = "Да[yes]==Нет[no]" // Создание клавиатуры
msg.entities = [] // Telegram entities (в Max автоматически преобразуются в HTML)

Параметр Telegram Max text text text parse_mode parse_mode format (`HTML` → html, Markdown`/`MarkdownV2 → `markdown`) keyboard inline-клавиатура вложение inline_keyboard entities entities преобразуются в HTML-теги и отправляются с format: html protect_content поддерживается игнорируется

Специальные типы кнопок

Ссылки (`link`):

msg.keyboard = "Посетить сайт[https://example.com]"

Web App. В Max кнопка open_app требует username бота, поэтому запись {https://...} превращается в обычную кнопку-ссылку (`link`):

msg.keyboard = "Открыть приложение{https://webapp-url.com}"

Ссылка на пользователя tg://user?id=... в Max не поддерживается: кнопка пропускается, в карточку лида пишется отладочное сообщение.

Справочник методов

Основные методы отправки

• send() — отправка нового сообщения;сообщения (`POST /messages`). ID отправленного сообщения сохраняется в атрибут лида max_last_message_id;
• edit() — редактирование существующего сообщения;
  сообщения (`PUT /messages?message_id=`): меняются текст, формат и клавиатура;
• addReplyToText() — добавлениепосле ответанажатия кнопки убирает клавиатуру и добавляет к существующемутексту сообщению;
  сообщения ➤ <текст нажатой кнопки>. Для текстового ввода (`write`) только убирает клавиатуру;
• removeInlineKeyboard() — удаление клавиатуры. К тексту сообщения добавляется ➤ 🔠;

removeReplyKeyboard() — в Max нет reply-клавиатур, поэтому метод убирает кнопки с последнего сообщения и отправляет текст _remove_keyboard_text, если он задан.

В Max клавиатура — это вложение сообщения. При редактировании остальные вложения исходного сообщения сохраняются, меняется только inline_keyboard.

Получение информации

• getMessagePayload() — получение информации о сообщении из вебхука:
  
• message_id — ID сообщения;
  сообщения (`mid`). Для нажатия кнопки — mid сообщения с клавиатурой;
• text — текст сообщения/кнопки;
  
• input_type — тип ввода (`'write'` / `'press'`);
  
• callback_data — данные колбэка;
  колбэка (без префикса `btn_static_`);
• callback_id — идентификатор колбэка Max (только для нажатия кнопки);

original_reply_markup — клавиатура исходного сообщения; payload — полные данные вебхука.

Обработка ответов пользователя:

// Проверка типа ввода
if (msg.getMessagePayload()?.input_type == "write") {
    // Пользователь написал текст
}

// Проверка нажатия кнопки
if (msg.getMessagePayload()?.callback_data == "button_id") {
    // Пользователь нажал кнопку
}

Структура вебхука Max отличается от Telegram: для нажатия кнопки (`message_callback`) сообщение с клавиатурой лежит в payload.message, а данные нажатия — в payload.callback. Для текста (`message_created`) текст находится в payload.message.body.text. Плагин приводит это к единому виду getMessagePayload().

Форматирование текста и entities

Формат строки клавиатуры полностью совпадает с Telegram-плагином.

Max принимает форматирование через параметр format: html или markdown.
HTML форматирование

Поддерживаются теги <b>, <i>, <u>, <s>, <code>, <pre>, <blockquote>, <a href="...">.

msg.text = "<b>Жирный текст</b>\n<i>Курсив</i>\n<code>Моноширинный текст</code>"
msg.parse_mode = "HTML"

Markdown форматирование

parse_mode со значениями Markdown, MarkdownV2 и md отправляется в Max как format: markdown. Синтаксис Markdown в Max не совпадает с MarkdownV2 Telegram (в частности, экранирование), поэтому для кросс-канальных скриптов используйте HTML.
Работа с entities

В Telegram entities позволяют сохранить форматирование, которое прислал пользователь. В Max их отправить нельзя, поэтому плагин автоматически преобразует msg.entities в HTML и отправляет сообщение с format: html. Поддерживаются типы: bold, italic, underline, strikethrough, code, pre, blockquote, text_link. Остальные типы пропускаются, спецсимволы текста экранируются.

let TelegramMessage = require('Common.Integrations.Telegram')
require('Common.Integrations.Max')

let msg = new TelegramMessage()
let messageData = lead.getJsonAttr("messageData")

msg.text = messageData?.text
msg.entities = messageData?.entities

// Не используйте одновременно parse_mode и entities

Важно: входящее форматирование Max приходит в message.body.markup, а не в entities, поэтому «эхо» форматирования пользователя из Max через entities без дополнительной конвертации не работает.
Отправка медиагрупп

Глобальная функция sendMediaGroup для лидов Max отправляет вложения в Max. Типы элементов приводятся так: photo`/`image → image, document`/`file → file, video → video, audio → audio. Для Telegram-лидов работает оригинальная реализация.

Рекомендации по работе с файлами

Всегда проверяйте наличие вложения (`attachments?.[0]?.url`) перед скачиванием. Сохраняйте URL, который вернул bot.downloadFileFromUrl(), а не исходный URL Max — он может устареть. Не используйте Telegram file_id для Max: идентификаторы вложений в каналах разные.

Входящие файлы обрабатываются стандартными методами бота — так же, как в Telegram-плагине.

Совместимость с Telegram-плагином

Ограничения Max

Текст кнопки — до 128 символов, payload кнопки — до 1024 символов. Ссылки на локальные адреса (`http://127.0.0.1`) не принимаются при подключении вебхука Max — нужен публичный HTTPS-адрес. Нажатие кнопки приходит как message_callback; для текстового ввода — message_created.

Подробнее примеры использования, форматы клавиатуры и лучшие практики смотрите в Документации Telegram-плагина