Форматированные сообщения в Telegram в Metabot

Быстрый гайд + пример собственного плагина

В Metabot сообщения в мессенджеры можно отправлять не только через стандартные команды конструктора, но и программно — напрямую из JavaScript-кода, используя плагины.

Это особенно полезно, когда вам нужно:

• гибко управлять форматированием текста;
• выбирать parse mode (HTML / Markdown / MarkdownV2);
• централизовать логику отправки сообщений;
• подготовить основу под мультиканальную отправку (Telegram, WhatsApp, WebChat и др.).

В этом гайде разберём, как отправлять форматированные сообщения в Telegram с помощью плагина Common.Helpers.SendFormattedMessage.

---

Зачем отдельный плагин для форматированных сообщений

На первый взгляд Telegram позволяет просто вызвать bot.sendMessage. Но на практике быстро появляются проблемы:

• разные режимы форматирования (HTML, Markdown, MarkdownV2);
• необходимость экранирования символов (особенно в MarkdownV2);
• опции Telegram API (например, превью ссылок);
• обработка ошибок и возврат результата выполнения;
• повторное использование кода в разных сценариях и модулях.

Поэтому в Metabot мы выносим эту логику в отдельный helper-плагин, который:

• инкапсулирует работу с Telegram API;
• принимает текст + формат;
• возвращает стандартизированный результат выполнения.

---

Как использовать sendFormattedMessage

Подключение плагина

В любом JS-скрипте (endpoint, custom-command, handler кнопки и т.д.):

const { sendFormattedMessage } = require('Common.Helpers.SendFormattedMessage')

---

Пример отправки форматированного сообщения

let message = `
*Я — Орион.*
Я — *навигатор Корпуса Операторов*.

Я помогаю людям *ориентироваться в сложных системах*:
технологиях, ролях, командах и *собственных траекториях*.

*Я не продаю курсы* и *не обещаю быстрых результатов*.

Если ты здесь —
значит, тебе *интересна сложность*.

Для начала мне нужно немного понять:
*зачем ты пришёл*
и *в какой форме ты сейчас живёшь*.

Это займёт *пару минут*.`

sendFormattedMessage(message, 'Markdown')

Здесь:

• текст оформлен в Telegram Markdown;
• формат явно передаётся вторым аргументом;
• сообщение отправляется напрямую через ядро, минуя визуальный конструктор.

---

Поддерживаемые форматы Telegram

Плагин поддерживает стандартные режимы Telegram API:

Формат	Когда использовать	Особенности
HTML (по умолчанию)	когда нужен стабильный контроль	не требует сложного экранирования
Markdown	для простого форматирования	ограниченный синтаксис
MarkdownV2	когда нужен расширенный Markdown	требует экранирования почти всех спецсимволов

Практическая рекомендация

• HTML — самый безопасный и предсказуемый вариант.
• Markdown — удобен для быстрых текстов и прототипов.
• MarkdownV2 — мощный, но сложный, используйте осознанно.

Подробные правила форматирования смотрите в официальной документации Telegram.

---

Где находится код плагина

Плагин размещается в общем пространстве helpers:

Common.Helpers.SendFormattedMessage

Структура плагина следующая:

• экспортируемая функция sendFormattedMessage(message, parseMode, options)
• внутри:
  • формирование apiAdditionalParams для Telegram (parse_mode, disable_web_page_preview);
  • вызов bot.sendMessage(...);
  • обработка ошибок через стандартный response-модуль.

/** 
 * Плагин для отправки форматированных сообщений в мессенджер (например, Telegram).
 * Автор: @ArtemGarashko
 * Версия: 1.0
 * Дата последнего обновления: 24.02.2025
 * 
 * Этот плагин используется для отправки форматированных сообщений в мессенджер.
 * Рекомендуется использовать формат HTML т.к. он не требует эскейпирования символов в отличие от MarkdownV2.
 * В случае ошибки при отправке сообщения, плагин использует Response для формирования ответа.
 */

// Подключаем Response плагин для обработки ответов
const { getErrorResponse, getSuccessResponse } = require('Common.Utils.Response');

/** 
 * Функция для отправки форматированного сообщения в мессенджер.
 * Использует Response плагин для обработки ответов.
 *
 * Примеры для каждого parseMode:
 * - 'HTML': <b>Привет</b> мир! — Выведет "Привет" жирным шрифтом.
 * - 'Markdown': *Привет* мир! — Выведет "Привет" курсивом.
 * @param {string} message - Текст сообщения, которое вы хотите отправить.
 * @param {string} [parseMode='HTML'] - Форматирование текста. Может быть:
 *  - 'HTML' (по умолчанию)
 *  - 'Markdown'
 *  - 'MarkdownV2'
 * @param {Object} [options={}] - Дополнительные параметры.
 * @param {boolean} [options.disableLinksPreview=true] - Отключить ли превью ссылок (по умолчанию true).
 * @returns {Object} - Возвращает успешный или ошибочный ответ в зависимости от результата.
 */
function sendFormattedMessage(message, parseMode = 'HTML', options = {}) {
    // Получаем значение для отключения превью ссылок из options (по умолчанию true)
    const disableLinksPreview = options.disableLinksPreview !== undefined ? options.disableLinksPreview : true; 

    // Устанавливаем параметры для API Telegram
    let apiAdditionalParams = {
        "parse_mode": parseMode, 
        "disable_web_page_preview": disableLinksPreview 
    };

    try {
        // Отправляем сообщение через Telegram API
        bot.sendMessage(message, null, null, apiAdditionalParams);
      
        // Возвращаем успешный ответ через Response плагин
        return getSuccessResponse({ message: 'Сообщение отправлено успешно' });
    } catch (error) {
        // В случае ошибки возвращаем ошибку через Response плагин
        return getErrorResponse('Не удалось отправить сообщение', error.message);
    }
}

module.exports = {
    sendFormattedMessage
}

⚠️ Исходный код, приведённый выше, актуален на момент публикации статьи. На серверах Metabot может использоваться более новая версия плагина с изменениями и доработками. Используйте код как ориентир и архитектурный шаблон.

---

Возврат результата и обработка ошибок

Важно: плагин не просто отправляет сообщение, но и возвращает результат выполнения.

Для этого используется общий модуль:

Common.Utils.Response

• getSuccessResponse(...)
• getErrorResponse(...)

Таким образом:

• при успехе вы получаете { success: true, ... };
• при ошибке — { success: false, error: true, message: ... }.

Это удобно, если:

• вы хотите анализировать результат отправки;
• логировать ошибки;
• строить цепочки логики (например, fallback-сценарии).

📌 Подробный разбор этого подхода будет в отдельной статье → «Стандартизация успешных ответов и ошибок в Metabot».

---

Почему это low-code, а не просто JS

Обратите внимание на архитектурный момент:

• мы не используем визуальную команду конструктора;

• мы вызываем отправку сообщения программно;

• но при этом:

  • работаем внутри экосистемы Metabot;
  • используем общий стандарт ответов;
  • можем переиспользовать код в любых сценариях.

Это и есть философия Metabot:

low-code как база + full-code там, где это действительно нужно.

---

Как расширять плагин дальше

Текущая версия — минималистичная, но она легко расширяется:

• добавить Telegram-специфичные опции (reply_markup, entities, protect_content);

• прокинуть дополнительные options без изменения API;

• реализовать аналогичные helpers под:

  • WhatsApp,
  • VK,
  • WebChat,
  • email,
  • push-уведомления.

По сути, sendFormattedMessage — это точка абстракции, от которой удобно строить мультиканальную систему сообщений.