n8n-nodes-telegram-markdown-sender

An n8n community node that sends standard Markdown messages to Telegram with automatic conversion to Telegram-compatible formats (MarkdownV2 or HTML).

The Problem

Sending Markdown to Telegram is painful. Telegram's MarkdownV2 format requires escaping 18 special characters (_, *, [, ], (, ), ~, `, >, #, +, -, =, |, {, }, ., !), and the escaping rules differ depending on context (body text vs. code blocks vs. URLs). This causes frequent "Bad Request: can't parse entities" errors — especially when piping AI-generated content (ChatGPT, Claude, etc.) directly to Telegram.

This node solves it by accepting standard Markdown and handling all conversion and escaping automatically.

Features

• Automatic Markdown conversion — Write standard Markdown, get Telegram-compatible output
• Dual format support — Convert to MarkdownV2 or HTML (recommended)
• Smart message splitting — Messages over 4096 characters are automatically split at natural break points
• Photo support — Send photos with Markdown captions (URL or binary data)
• Convert-only mode — Use the conversion engine without sending, for integration with other nodes
• AI Tool compatible — Flagged as usableAsTool, so AI agents in n8n can call it directly
• Self-hosted Bot API support — Custom baseUrl for private Telegram Bot API servers
• Forum/topic support — Target specific topics via messageThreadId

Supported Markdown Elements

| Element | Syntax | Telegram Output | |---------|--------|-----------------| | Bold | **text** | text | | Italic | *text* | text | | Underline | __text__ | underlined text | | Strikethrough | ~~text~~ | ~~strikethrough~~ | | Inline code | `code` | code | | Code block | ```lang ... ``` | syntax-highlighted block | | Blockquote | > text | quoted text | | Link | [text](url) | clickable link | | Heading | # Title | bold title (with emoji prefix for H1) | | Ordered list | 1. item | numbered list | | Unordered list | - item | bulleted list | | Table | | col | col | | preformatted table | | Spoiler | \|\|text\|\| | hidden spoiler text | | Image | ![alt](url) | linked image |

Installation

Via n8n Community Nodes (Recommended)

1. Open your n8n instance
2. Go to Settings > Community Nodes
3. Click Install a community node
4. Enter: n8n-nodes-telegram-markdown-sender
5. Click Install

Via npm (Self-hosted)

cd ~/.n8n
npm install n8n-nodes-telegram-markdown-sender

Then restart your n8n instance.

Setup

1. Create a Telegram Bot

1. Open Telegram and talk to @BotFather
2. Send /newbot and follow the prompts
3. Copy the Bot Token (e.g., 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

2. Get Your Chat ID

• For private chats: Send a message to your bot, then visit https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates to find your chat ID
• For groups: Add the bot to the group and check getUpdates — group IDs are negative numbers (e.g., -1001234567890)
• For channels: Use the channel username (e.g., @mychannel) or the numeric ID

3. Configure Credentials in n8n

1. In your n8n workflow, add the Telegram Markdown Sender node
2. Click Create New Credential
3. Enter your Bot Token
4. (Optional) Change the Base URL if using a self-hosted Telegram Bot API server
5. Click Save — the credential will be automatically tested

Usage

Operation: Send Message

Sends a Markdown-formatted message to a Telegram chat.

Required fields:

• Chat ID — The target chat/group/channel ID
• Markdown Text — Your message in standard Markdown

Optional fields:

• Parse Mode — HTML (recommended, default) or MarkdownV2
• Disable Link Preview — Prevent URL previews in the message
• Disable Notification — Send silently
• Reply To Message ID — Reply to a specific message
• Message Thread ID — Target a specific forum topic
• Protect Content — Prevent forwarding/saving
• Reply Markup — Custom keyboard (JSON format)

Example input:

# Weekly Report

**Project Alpha** is on track.

## Highlights
- Completed API integration
- Fixed 3 critical bugs
- Performance improved by ~40%

> Next milestone: v2.0 release on Friday

See the [dashboard](https://example.com) for details.

Output:

{
  "success": true,
  "messageId": 12345,
  "isSplit": false,
  "totalChunks": 1
}

Operation: Send Photo

Sends a photo with an optional Markdown caption.

Required fields:

• Chat ID — The target chat/group/channel ID
• Photo Source — URL or Binary Data
• Photo URL / Binary Property — The image source

Optional fields:

• Caption — Markdown-formatted caption text
• Parse Mode — HTML (recommended) or MarkdownV2
• Has Spoiler — Hide photo behind a spoiler overlay
• Disable Notification — Send silently
• Message Thread ID — Target a specific forum topic
• Protect Content — Prevent forwarding/saving
• Reply Markup — Custom keyboard (JSON format)

Output:

{
  "success": true,
  "messageId": 12346
}

Operation: Convert Only

Converts Markdown to Telegram format without sending. Useful for previewing the output or chaining with other nodes.

Required fields:

• Markdown Text — Your message in standard Markdown
• Output Format — HTML or MarkdownV2

Output:

{
  "convertedText": "<b>Hello</b> world",
  "originalLength": 16,
  "convertedLength": 22
}

Workflow Examples

AI Output to Telegram

[ChatGPT Node] → [Telegram Markdown Sender]

Connect any AI node's output directly — the node handles all Markdown escaping automatically.

Report with Chart Image

[HTTP Request (get chart)] → [Telegram Markdown Sender (sendPhoto)]

Fetch a chart image and send it with a Markdown-formatted caption.

Long Message Handling

[Code Node (generate report)] → [Telegram Markdown Sender]

Messages exceeding 4096 characters are automatically split into multiple messages at natural break points (headings, horizontal rules, paragraphs), with page numbers ([1/3], [2/3], [3/3]) appended.

Convert and Route

[Telegram Markdown Sender (convertOnly)] → [IF Node] → [Other Nodes]

Use convert-only mode to transform Markdown and then route or process the result in downstream nodes.

HTML vs MarkdownV2

| Aspect | HTML (Recommended) | MarkdownV2 | |--------|-------------------|------------| | Reliability | Higher — fewer escaping edge cases | Lower — complex escaping rules | | Telegram support | Full | Full | | Nested formatting | Better support | Limited | | Recommended for | Most use cases | When you specifically need MD output |

Recommendation: Use HTML mode (the default). It produces more reliable results, especially with complex or AI-generated content.

Message Splitting Behavior

When a converted message exceeds 4050 characters (just under Telegram's 4096 limit):

1. The node looks for a natural split point near the middle:
   • First priority: --- (horizontal rule)
   • Second priority: # (heading)
   • Third priority: newline
2. Each chunk gets a page indicator: [1/N]
3. Chunks are sent with a 1-second delay between them (Telegram rate limiting)
4. All message IDs are returned in the messageIds array

Error Handling

• The node uses n8n's standard continueOnFail() mechanism
• On failure: returns { error: "error message" } instead of stopping the workflow
• Common errors:
  • "Bad Request: chat not found" — Invalid Chat ID or bot not added to group
  • "Unauthorized" — Invalid bot token
  • "Too Many Requests" — Rate limited; the node already adds delays for split messages

Development

# Clone the repository
git clone https://github.com/ice3x2/n8n-nodes-telegram-markdown-sender.git
cd n8n-nodes-telegram-markdown-sender

# Install dependencies
npm install

# Build
npm run build

# Watch mode (for development)
npm run build:watch

# Lint
npm run lint
npm run lint:fix

Running E2E Tests

Create a .env.test file:

TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id

Then run:

npx vitest run tests/e2e-telegram.test.ts

Compatibility

• n8n: 1.0.0+
• Node.js: 18+
• n8n Nodes API: v1

License

MIT - Copyright (c) 2025 Snoworca