A Markdown snippet with bold, italic, code, a quote and a link, and the Telegram message it becomes

A TypeScript library for Telegram bots that answer with Markdown, usually written by an LLM. It turns the Markdown into a message Telegram accepts: no manual escaping, no formatting that breaks halfway through a reply, no message rejected for a stray character.

I wrote it for my own bot, which sends LLM replies both as ordinary messages and as Telegram’s new rich messages.

What it does

One Markdown text, every format Telegram takes:

  • Entities: plain text plus a list of formatting entities for sendMessage. There’s no parse_mode, so there’s nothing to escape.
  • Rich messages for sendRichMessage (Bot API 10.1+): real headings, tables, checkboxes, math, footnotes and media.
  • MarkdownV2, for the places that only take a parse_mode string.
  • Telegraph pages, for texts too long for a chat.

Each format has a splitter that cuts long replies into messages within Telegram’s limits, and streaming helpers show a reply while the LLM is still writing it, with the stop button from Bot API 10.3.

Based on a Python library

It’s a TypeScript port of telegramify-markdown, a Python library by sudoskys, and it follows its releases. Everything is ported except rendering Mermaid diagrams.

A native Rust parser

The Markdown is parsed by pulldown-cmark, a CommonMark parser written in Rust. The Python library uses the same parser through its Python bindings; here it is compiled into a native Node.js module with N-API. Parsing runs as native code, and the TypeScript side only walks the parser’s events and renders them. JavaScript strings count UTF-16 code units, just like Telegram’s entity offsets, so no offset conversion is needed either.

Prebuilt binaries are built for seven platforms: macOS (Intel and Apple silicon), Windows x64, and Linux x64 and arm64 with glibc or musl (Alpine). The install picks the right one; on anything else you build it from source.

Tested against Telegram

On top of the port, it has more than 300 tests, and the live tests send real messages through the Bot API to check that Telegram accepts them. The output follows Telegram’s API to the letter: rich messages use Telegram’s own field names (Telegram silently ignores fields it doesn’t know), splitting counts blocks and media the way Telegram does, and entity offsets stay correct after non-Latin text. It’s up to date with Bot API 10.4.

Install it

It’s installed from GitHub, not from the npm registry. The command, the requirements and the platform notes are in the Installation section of the README.

import { convert } from 'tg-md-msg';

const { text, entities } = convert('**Hello** from `tg-md-msg`');
await bot.api.sendMessage(chatId, text, { entities });

It needs Node.js 18 or later and is ESM only. It’s open source (MIT): github.com/podgorniy/ts-md-msg.

Source code on GitHub

Discussion

Comments load from remark42.podgorniy.net…