Skip to content
All posts

Telegram Markdown: MarkdownV2, Bot API & In-App Formatting (2026)

Complete Telegram formatting guide — MarkdownV2 vs legacy Markdown vs HTML parse modes, the full escaping rules, spoilers, custom emoji, and in-app shortcuts that actually work.

Telegram supports rich text in two completely different worlds: the app, where you format messages by hand, and the Bot API, where your code sends formatted text using a parse_mode. The syntax overlaps with Markdown but has its own escaping rules — and getting one character wrong makes the Bot API reject your whole message with a 400 Bad Request.

This guide covers both: what you can type in the Telegram app, and exactly how MarkdownV2, legacy Markdown, and HTML parse modes behave when you send messages programmatically.

Two ways to format in Telegram

ContextHow formatting works
App (you typing)Select text → format menu, keyboard shortcuts, or inline markdown symbols
Bot API (your code)Send parse_mode: "MarkdownV2", "Markdown", or "HTML"

If you only chat in Telegram, jump to in-app formatting. If you build bots or automation, the MarkdownV2 section is the one that matters.

In-app formatting

When you type a message in any Telegram client, you can format selected text:

ActionShortcut (desktop)Inline symbols
BoldCtrl/⌘ + B**bold**
ItalicCtrl/⌘ + I__italic__
UnderlineCtrl/⌘ + U—
StrikethroughCtrl/⌘ + Shift + X~~strike~~
MonospaceCtrl/⌘ + Shift + M`code`
SpoilerCtrl/⌘ + Shift + P||spoiler||
LinkCtrl/⌘ + K[text](url)

Telegram's desktop and mobile apps auto-convert the inline symbols as you type. Select text first for the most reliable result — typing symbols around long phrases is error-prone.

MarkdownV2 — the current standard

For bots, MarkdownV2 is the recommended parse mode. Send it in your API call:

{
  "chat_id": 123456789,
  "parse_mode": "MarkdownV2",
  "text": "*bold* _italic_ __underline__ ~strike~ ||spoiler||"
}

Full MarkdownV2 syntax

*bold text*
_italic text_
__underline__
~strikethrough~
||spoiler||
`inline code`
[inline link](https://trymarkdownviewer.com)
[user mention](tg://user?id=123456789)

Code blocks with an optional language:

```python
print("hello from a bot")
```

The escaping rule that breaks everyone

In MarkdownV2, these characters are reserved and must be escaped with a backslash \ everywhere they appear as literal text:

_ * [ ] ( ) ~ ` > # + - = | { } . !

That means a plain sentence like Cost: $4.99 (limited!) must be sent as:

Cost: $4\.99 \(limited\!\)

Miss one and the Bot API returns:

Bad Request: can't parse entities

Practical rule: escape every reserved character in the literal parts of your text, and leave the formatting delimiters unescaped. Inside `code` and ``` blocks, only ` and \ need escaping. Inside (...) link URLs, only ) and \ need escaping.

Most bot frameworks ship an escapeMarkdownV2() helper — use it on dynamic values (usernames, prices, file names) before interpolation.

Legacy Markdown (deprecated)

The original parse_mode: "Markdown" is simpler but deprecated and far less capable:

*bold*
_italic_
`code`
[link](https://example.com)

No underline, no strikethrough, no spoilers, and no nested entities. Telegram keeps it for backward compatibility only — new code should use MarkdownV2 or HTML.

HTML parse mode

If escaping fights you, HTML mode is often easier to generate from a template engine:

{ "parse_mode": "HTML", "text": "<b>bold</b> <i>italic</i> <code>code</code>" }

Supported tags:

<b>bold</b>  <strong>bold</strong>
<i>italic</i>  <em>italic</em>
<u>underline</u>
<s>strike</s>  <del>strike</del>
<span class="tg-spoiler">spoiler</span>
<a href="https://trymarkdownviewer.com">link</a>
<code>inline</code>
<pre>preformatted</pre>
<pre><code class="language-python">block</code></pre>
<blockquote>quote</blockquote>

In HTML mode you only escape <, >, and & (&lt;, &gt;, &amp;). For machine-generated messages, this is usually less fragile than MarkdownV2.

Converting source Markdown → Telegram HTML: render your Markdown to sanitized HTML with the Markdown render API, then map the allowed subset of tags. The render endpoint strips anything unsafe; you keep only the tags Telegram supports.

What Telegram does NOT support

FeatureStatus
Headings (# H1)❌ no heading entity — use bold
Tables❌ send as monospace block or image
Images via Markdown❌ use sendPhoto with a caption
Nested lists❌ no list entity — fake with • and indentation
Task checkboxes❌ use emoji ✅ / ⬜

Telegram has no concept of headings, lists, or tables as rich entities. For structured content, send a monospace block (preserves alignment) or render to an image.

Faking a table

```
Endpoint  Method  Auth
/render   POST    yes
/health   GET     no
```

Build the aligned text with the Markdown table generator, then wrap it in a code fence so the monospace font keeps columns lined up.

Spoilers and custom emoji

Spoilers hide text until tapped — great for plot details or answer reveals:

The killer was ||the butler||.

Custom emoji (premium feature) are sent as message entities via the API with custom_emoji_id, not through Markdown. Standard Unicode emoji work everywhere — grab shortcodes from the emoji picker.

Bot message recipes

Release notification

🚀 *Deploy complete*

Version: `2\.4\.0`
Region: `us\-east\-1`
Status: all checks passed ✅

[View logs](https://example.com/logs)

Note every . and - is escaped — required in MarkdownV2.

Error alert (HTML mode, easier to template)

🔴 <b>INC-284</b> — elevated latency
Impact: ~15% of requests &gt; 2s
<a href="https://example.com/inc/284">Runbook</a>

Code snippet share

```javascript
const md = await fetch("https://trymarkdownviewer.com/api/v1/render", {
  method: "POST",
  body: JSON.stringify({ markdown: "# Hello" }),
});
```

Telegram vs Slack vs Discord formatting

FeatureTelegramSlackDiscord
Bold*text* (V2)*text***text**
Italic_text__text_*text*
Strikethrough~text~~text~~~text~~
Spoiler||text||❌||text||
Underline__text__❌__text__
Link in messages[text](url)<url|text>bare URL
Headings❌❌# H1

Working across chat platforms? Keep the Slack guide and Discord guide handy — bold and link syntax differ on every one.

Common Telegram Markdown mistakes

1. Unescaped reserved characters. A stray ., -, or ! in MarkdownV2 kills the whole message. Escape dynamic values.

2. Mixing parse modes. You can only set one parse_mode per message. Pick MarkdownV2 or HTML, not both.

3. Legacy Markdown for new bots. It can't do underline, strikethrough, or spoilers. Use MarkdownV2.

4. Expecting headings or tables. They don't exist as entities — use bold and monospace blocks.

5. Forgetting nested-entity rules. In MarkdownV2, you can nest (bold inside italic), but the delimiters must not be ambiguous — escape literal delimiters inside.

Preview before you send

Draft your message in the Markdown editor to check structure, then:

  • Convert headings to bold lines (Telegram has no headings).
  • Wrap any table in a code fence so columns stay aligned.
  • Run dynamic strings through your framework's escapeMarkdownV2().
  • For bots, prefer HTML mode when text is template-generated — fewer escaping surprises.

For automated pipelines (CI → Telegram bot), render Markdown to HTML with the API and forward the supported tag subset.

Quick reference

Syntax (MarkdownV2)Result
*bold*bold
_italic_italic
__underline__underline
~strike~strikethrough
||spoiler||spoiler
`code`inline code
```lang fencecode block
[text](url)link
[name](tg://user?id=ID)user mention
\. \- \! …escaped literals

Telegram formatting is two skills: typing fast in the app, and escaping carefully in the Bot API. Learn MarkdownV2's reserved-character list (or switch to HTML mode) and your bot messages will stop returning can't parse entities.

Written by Markdown Viewer Team. Found this useful? Try the editor →

Keep reading

Hand-picked articles related to this one.