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
| Context | How 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:
| Action | Shortcut (desktop) | Inline symbols |
|---|---|---|
| Bold | Ctrl/⌘ + B | **bold** |
| Italic | Ctrl/⌘ + I | __italic__ |
| Underline | Ctrl/⌘ + U | — |
| Strikethrough | Ctrl/⌘ + Shift + X | ~~strike~~ |
| Monospace | Ctrl/⌘ + Shift + M | `code` |
| Spoiler | Ctrl/⌘ + Shift + P | ||spoiler|| |
| Link | Ctrl/⌘ + 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 & (<, >, &). 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
| Feature | Status |
|---|---|
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 > 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
| Feature | Telegram | Slack | Discord |
|---|---|---|---|
| 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.
Related articles
- Slack Markdown guide —
*bold*and<url|label>links - Discord Markdown guide — spoilers and underline too
- WhatsApp Markdown guide — even more limited formatting
- Markdown cheat sheet — standard syntax reference
- Safe Markdown → HTML for AI apps — sanitizing before send
Quick reference
| Syntax (MarkdownV2) | Result |
|---|---|
*bold* | bold |
_italic_ | italic |
__underline__ | underline |
~strike~ | strikethrough |
||spoiler|| | spoiler |
`code` | inline code |
```lang fence | code 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.
Master Markdown in Microsoft Teams — chat compose formatting, the differences from GitHub GFM, Adaptive Card markdown, and incoming-webhook message formatting for bots and CI.
Every WhatsApp formatting trick — bold, italic, strikethrough, monospace, bulleted and numbered lists, block quotes, and inline code — plus what breaks when you paste from elsewhere.
Every Slack Markdown feature explained — bold, italic, code, lists, quotes, links, block Kit vs mrkdwn, Canvas formatting, and the quirks that break when you paste from GitHub.