Форматирование: HTML в сообщениях

Telegram поддерживает два режима разметки — HTML и MarkdownV2, — и переключаются они строкой в поле ParseMode. В библиотеке для этого есть константа tgbotapi.ModeHTML со значением HTML: msg.ParseMode = tgbotapi.ModeHTML, и дальше весь текст сообщения разбирается как HTML-фрагмент. Набор тегов намеренно узкий: b и strong дают жирный, i и em — курсив, u подчёркивание, s зачёркивание, code — моноширинный фрагмент, pre — блок кода, a с href — ссылку, blockquote — цитату. Вложенность работает: жирный внутри ссылки, код внутри жирного. Никаких div, span и стилей — сервер примет только перечисленное, остальное либо упадёт, либо уйдёт как текст. Важно понимать механику: теги не рисует библиотека и не рисует ваш Go — они едут в Telegram как часть текста, и там уже превращаются в оформление. Поэтому и экранировать чужие угловые скобки нужно у себя, до отправки.

Пока текст сообщения написан вами, теги безопасны. Как только бот вставляет в разметку то, что прислал пользователь, появляется вторая сторона медали: строка с угловой скобкой ломает разбор. Классический сценарий — эхо-бот с ParseMode: пользователь пишет «люблю <3» или «2 < 3 и 5 > 4», и сервер отвечает ошибкой can't parse entities, сообщение не уходит вовсе. Ошибка приходит на конкретное сообщение: остальные отправки при этом работают, и в логах бот выглядит здоровым — падение видно только по команде конкретного пользователя. Лечение — html.EscapeString из стандартной библиотеки: функция превращает угловые скобки, амперсанд и кавычки в HTML-сущности, которые Telegram показывает как текст, а не читает как разметку. Правило разделения труда простое: свою разметку экранировать нельзя — жирный перестанет быть жирным, — а весь пользовательский ввод экранируется всегда, до склейки со строкой. Из этого следует порядок сборки: сначала экранируем ввод, потом обкладываем тегами, и никогда наоборот.

Почему в уроках курса HTML, если Markdown привычнее? Аргументы за MarkdownV2 — короткая запись: два символа обёртки вместо пары тегов. Аргументы против — экранирование: MarkdownV2 требует маскировать целую дюжину символов в пользовательском тексте — подчёркивания, звёздочки, скобки всех видов, дефисы в некоторых позициях, — и забытый символ даёт ту же can't parse entities. HTML-режим маскирует ровно три символа: скобку, амперсанд и кавычку, и делает это готовая функция стандартной библиотеки. Второй аргумент — строгость: HTML разбирается предсказуемо, а парсер Markdown в Telegram чувствителен к пробелам и переносу строк. Спорное на практике звучит так: если бот только ваш текст пишет без вставок — берите что нравится, разницы почти нет. Как только в шаблоне появляется пользовательский ввод, HTML с html.EscapeString экономит часы отладки, и я не видел обратных случаев. Переключение между режимами стоит ровно одну строку — поле ParseMode переприсваивается, — поэтому решение легко пересмотреть, если проект срастётся с вводом.

Бот-дневник из прошлых уроков подтверждает сохранённую запись карточкой: дата курсивом, сама запись как есть, счётчик серии жирным. Разметка собирается конкатенацией: date := record.Date.Format("02.01"), затем fmt.Sprintf("<i>%s</i>\n%s\n<b>Серия: %d дней</b>", date, html.EscapeString(record.Text), record.Streak). Три строки кода, а карточка выглядит живой — и в истории чата её видно с первого взгляда. Здесь работает тот же принцип, что и с callback_data из девятого урока: машинное и человеческое разведены. Хранение остаётся плоским текстом, разметка — слой отображения, и если однажды понадобится экспорт в другой канал, данные не придётся чистить от тегов. Захардкоженные в базу теги — типичный след новичка, который потом всплывает в CSV-выгрузках и уезжает на сайт вместе с браком.

Вторая категория падений случается без всякого ввода: бот собирает сообщение кусками и теряет закрывающий тег. Открывающий b есть, закрывающий забыт — и сервер либо ругается can't parse entities, либо оформляет жирным всё до конца сообщения: вместе с подписью и контактами. Лечится это дисциплиной сборки: разметку кусков собирают функциями, у каждой пары открывающий-закрывающий тег живёт в одной строке, а сообщение собирается конкатенацией готовых кусков. Полезная привычка — тестовая отправка самому себе в личку перед релизом: один ваш chat_id как первый получатель ловит сломанную разметку раньше пользователей. Обратная крайность — двойное экранирование, когда про html.EscapeString вспоминают дважды: пользователь видит &lt;b&gt; вместо жирного. Проверка простая: экранирует функция у границы ввода, ровно один раз, а не в каждом слое.

Служебные боты часто возвращают куски логов, диффы и таблицы — и тут раскрывается тег pre: многострочный блок моноширинным с сохранением переносов, читается как терминал. Нюанс тот же, что и с обычным вводом: строки лога полны угловых скобок и амперсандов, поэтому содержимое блока тоже проходит через html.EscapeString, и только потом обкладывается pre. Формат лучше делать коротким строкам — Telegram рисует блок без переносов, и длинная строка уезжает за экран телефона. Для больших отчётов честнее документ из урока про медиа — файл не упирается в лимит текстового сообщения, а pre остаётся для коротких выдержек в диалоге.

Освоив теги, новички обкладывают ими весь трафик бота: эхо с жирным, подтверждения курсивом, всё как в лендинге. Я считаю это ошибкой вкуса с реальной ценой: разметка уместна там, где есть структура — справка, карточки, отчёты, — и вредна в коротких диалоговых репликах, где она шумит и добавляет каждое сообщению пафос объявления. Граница рабочая: если сообщение длиннее трёх строк или содержит перечисление — разметка помогает; если это ответ «принял» или следующий вопрос анкеты — плоский текст честнее. Второй аргумент экономный: каждое сообщение с ParseMode проходит разбор на сервере, и баг разметки роняет его целиком, тогда как плоский текст сломать нечем. Третий — спокойствие пользователя: чат, в котором каждое второе сообщение оформлено как баннер, читается утомительно, и люди быстрее отключают уведомления. Разметка — приправа, а не блюдо; это правило не из документации, но из поддержки ботов следует напрямую.