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.
• sendMessage supports 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