Skip to content

fix(telegram): switch formatting from MarkdownV2 to HTML - #1457

Closed
llbn wants to merge 1 commit into
NousResearch:mainfrom
llbn:fix/telegram-message-formatting
Closed

fix(telegram): switch formatting from MarkdownV2 to HTML#1457
llbn wants to merge 1 commit into
NousResearch:mainfrom
llbn:fix/telegram-message-formatting

Conversation

@llbn

@llbn llbn commented Mar 15, 2026

Copy link
Copy Markdown
Contributor

What does this PR do?

Switches the Telegram adapter's outbound message formatting from MarkdownV2 to HTML parse mode, fixing broken formatting on chunked messages.

Problem

The adapter formats the entire message to MarkdownV2 first, then chunks the result to fit Telegram's 4096-char limit. After chunking, truncate_message() appends a raw (1/2) indicator to each chunk. Since ( and ) are MarkdownV2 special characters that must be escaped, the unescaped indicator makes the chunk invalid MarkdownV2. Telegram rejects it and the adapter falls back to plain text.
An alternative to switching parse modes would be to fix the chunk indicator escaping. However, this is awkward in practice — truncate_message() is shared across all adapters in base.py, and nearly every bracket character ((), [], {}) is MDV2-special, making it hard to choose a safe indicator format. Fixing the indicator would also leave the underlying complexity of the MDV2 pipeline in place (18-char escaping with a placeholder protection system).

Solution

Switch to Telegram's HTML parse mode. HTML only requires escaping 3 characters (&, <, >) — parentheses are not special, so chunk indicators work without modification.
The send flow is also reversed to chunk-then-format — raw markdown is chunked first (where the base chunker's splitting and indicator appending is safe), then each chunk is formatted to HTML independently.

Additional improvements

The new HTML pipeline supports elements that the MDV2 pipeline did not handle:

  • Blockquotes (> text -> <blockquote>) — Telegram renders these natively with a left-border indicator
  • Strikethrough (~~text~~ -> <s>) — not mapped in the old pipeline
  • Tables (detected by |---| separator rows -> <pre>) — rendered as monospace for column alignment
  • Horizontal rules (--- -> ———) — visual separator

Related Issue

Fixes #1456

Type of Change

Bug fix (non-breaking change that fixes an issue)

Changes Made

  • gateway/platforms/telegram.py — replace _escape_mdv2/_strip_mdv2 with _escape_html/_strip_html, rewrite format_message() pipeline for HTML output, reverse send flow to chunk-then-format, update send()/edit_message() to use ParseMode.HTML
  • tests/gateway/test_telegram_format.py — rewrite all assertions for HTML output (68 tests, including chunking regression test)

How to Test

  1. Start the gateway with a Telegram bot configured
  2. Trigger a long LLM response that will be chunked (e.g. a news digest with bold section headers, linked article titles, and an italic article count)
  3. Verify both chunks render with proper formatting (bold, links, italic)
  4. Test shorter messages too — bold, inline code, code blocks, links, blockquotes, strikethrough
  5. Run pytest tests/gateway/test_telegram_format.py -v — all 68 tests should pass

Checklist

Code

  • I've read the Contributing Guide
  • My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
  • I searched for existing PRs to make sure this isn't a duplicate
  • My PR contains only changes related to this fix/feature (no unrelated commits)
  • I've run pytest tests/ -q and all tests pass
  • I've added tests for my changes (required for bug fixes, strongly encouraged for features)
  • I've tested on my platform: macOS 26.2, alpine 3.23.3

Documentation & Housekeeping

  • I've updated relevant documentation (comments, docstrings)

  - Replace _escape_mdv2/_strip_mdv2 with _escape_html/_strip_html
  - Refactor format_message() pipeline to produce Telegram HTML tags
  - Reverse send flow to chunk-then-format, fixing invalid chunks
    caused by unescaped (N/M) indicators in formatted MarkdownV2
  - Add blockquote, strikethrough, table, and horizontal rule support
  - Rewrite telegram-format tests for HTML assertions
@teknium1

Copy link
Copy Markdown
Contributor

Thanks for the fix. I merged PR #1478 for #1456 instead, which addresses the same bug with a narrower change: it keeps the existing MarkdownV2 pipeline and escapes only the auto-appended chunk indicator suffix that was breaking Telegram parsing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: Telegram formatting falls back to plain text on chunked messages

2 participants