Telegram Design
Readable Telegram messages: safe formatting, code blocks, pagination and clear actions.
- Updated:
- Words:
- 401
- Weekly downloads:
- 0
- Total downloads:
- 1
Related links
Telegram Design
Design for the mobile chat: result or status first, useful details after, and a clear action. Summarize long outputs and offer the file when it is necessary to keep them complete.
Formatting and limits
- For arbitrary model or tool output, use plain text. If you need
formatting, generate entities or HTML supported by Telegram from escaped data.
Escape
&,<, and>in text, and also quotes in attributes; avoid double escapes. - In MarkdownV2, escape according to context: text, link, or code. Markdown conversion must respect that structure, not rely on global substitutions.
sendMessagesupports 4096 characters after interpreting entities. Check the limits of the method used; captions have different limits.- Split by content units and apply formatting to each fragment. Close and reopen code blocks; preserve entities, links, escapes, and surrogate pairs. Entity offsets are calculated in UTF-16 units.
- Use real line breaks and check the copied text. Replace wide tables with key/value pairs; use labeled links, short file names, and monospaced code.
Actions and progress
Distinguish request received, pending, in progress, completed, and failed according to the actual result. Update a progress message with limited frequency and keep a final summary.
Differentiate agent content from bot controls. Authorization buttons belong to the bot; a command included in a model response is shown as text and is not processed as a human order.
Keep callback_data between 1 and 64 bytes with an opaque identifier. Store the
action and its scope on the server, without including commands, secrets, or private paths
in the button. Respond with answerCallbackQuery also when canceling or rejecting
an expired action.
On HTTP 429, respect retry_after and use a bounded queue. A formatting error
can be resolved with a single send in safe plain text; limit retries and
avoid duplicating confirmed messages. Exclude from logs the URLs that contain
the bot token.
Verification
Test reserved characters, emoji, long URLs, code that exceeds the limit, and pagination. Each fragment must be valid and preserve the content; each button must act on the resource shown. Simulate rejected formatting, editing without changes, and rate limiting. Reserve real sends to an authorized test chat.
Reference: https://core.telegram.org/bots/api#formatting-options
Versions (1)
| Version | Downloads (weekly) | Downloads (total) | Published |
|---|---|---|---|
0.1.0latest First published version. | 0 | 1 | October 14, 2026 |