Skip to main content

Message formatting: link previews, text styles, mentions, and media

Disable link previews, send photo/video/animation with caption, use entities text_mention and Markdown links, plus auto @/URL/command rules.

In short

Turn off preview cards with link_preview_options.is_disabled = true. Mix media via sendPhoto / sendVideo / sendAnimation + caption. Explicit entities currently support text_mention; Markdown/HTML links use parse_mode.


Overview

These controls shape how bot text and media appear in chat. Field-level rules: core.mp.net/bots.

Disable link preview cards

On sendMessage, set link_preview_options: { "is_disabled": true } to skip normal link previews and also send web_app entry messages as plain text without a MiniApp card. Legacy disable_web_page_preview: true maps to the same flag when link_preview_options is absent.

{
"chat_id": 12345,
"text": "https://example.com/path",
"link_preview_options": { "is_disabled": true }
}

Mixed media + caption

  • Send image / video / GIF with sendPhoto, sendVideo, or sendAnimation.

  • Put the accompanying text in caption (same bubble). Clients size media to a fixed width with proportional height; long captions wrap. Exact length limits follow the official method pages.

  • Existing file_id reuse is not supported — use HTTPS URL or multipart upload.

Use caption_entities with sendPhoto, sendVideo, sendAnimation or sendDocument. Omit it to allow automatic mention detection. An empty array disables detection for that caption. Do not pass reply_markup to sendDocument, which rejects it with 400.

MessageEntity: two @ styles

  • Raw @username in text: when you omit entities, the server may auto-resolve unique usernames to mentions.

  • Explicit entities with type: "text_mention" + user.id: visible text can be any label, anchored to that user id (group member validation applies).

  • Today, public entities input supports only text_mention. Do not combine with web_app entry cards yet.

Control automatic mentions

Omit entities to allow exact, case-sensitive @username matching. Pass entities: [] to disable it. The default threshold is 100 raw mention tokens per message. A clickable mention does not necessarily send a group reminder. Only confirmed group members receive group @ reminders.

Use UTF-16 code units for offset and length. In 🚀 @Chen, use offset 3 and length 5. For invitations, send the selected group members’ IDs as explicit entities.

Markdown / HTML links

parse_mode accepts Markdown or HTML. For Markdown-style hyperlinks use [label](URL) when parse_mode is Markdown.

Related

Source of truth

Did this answer your question?