Сущности сообщения — это структурированный, невидимый способ Telegram размечать текст. Вместо встраивания символов форматирования в сам текст Bot API описывает каждый стилизованный фрагмент — жирный, курсив, ссылку, упоминание и подобное — отдельной записью, которая называет тип форматирования и смещение с длиной участка текста, который он охватывает. Это альтернатива инлайн-разметке вроде MarkdownV2: когда вы отправляете текст с синтаксисом MarkdownV2, Telegram разбирает этот синтаксис и превращает его в сущности ещё до сохранения и доставки сообщения, поэтому обычный текст и его форматирование в итоге представлены раздельно, а не переплетены.
Инлайн-язык разметки вроде MarkdownV2 держит форматирование и содержимое в одной строке — жирное слово оборачивается звёздочками прямо там, где оно стоит. Сущность сообщения вместо этого описывает форматирование как координаты в базовом обычном тексте: какой тип форматирования применён, где он начинается и какую длину имеет — в кодовых единицах UTF-16, а не в символах, что важно для всего с эмодзи, поскольку они считаются как две единицы, а не одна. Текст, который показывает клиент, вообще не содержит символов разметки — форматирование полностью живёт в сопроводительном списке фрагментов.
Отделение структуры от содержимого устраняет целый класс проблем с экранированием: фрагмент обычного текста может содержать любой символ, включая такой, который в инлайн-синтаксисе пришлось бы экранировать, — ведь в самом тексте ничего не трактуется как инструкция форматирования. Это также облегчает удаление или игнорирование форматирования: клиент без поддержки расширенного текста может просто прочитать обычный текст и пропустить список сущностей, тогда как удаление инлайн-разметки сначала потребовало бы её разбора.
MarkdownV2 — это один из форматов ввода, которые Telegram принимает и преобразует, а не конкурирующее представление. Отправьте сообщение с форматированием MarkdownV2 — и Telegram разберёт звёздочки, подчёркивания и скобки в тексте, а затем сохранит результат как обычный текст плюс сущности. Посты Autogram выходят именно так: сгенерированный контент экранируется и форматируется как MarkdownV2 на выходе, а преобразование в сущности выполняет уже сам Telegram. Чтение сообщения обратно показывает только форму сущностей — исходный синтаксис MarkdownV2, который набрал отправитель, нигде не сохраняется.
Автоматизируйте публикацию в Telegram с помощью AI-контента, оценки качества и умного планирования.