Skip to main content

Rich bot messages: link previews, entities, and mixed 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.

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.

Auto-recognition in bot-sent text

  • URL: starts with http:// / https:// until whitespace; trailing punctuation excluded; no scheme → not a URL.

  • @username: @ + [A-Za-z0-9_-] until whitespace. [email protected] is email-like text, not a user mention.

  • /command: / + [A-Za-z0-9_] until whitespace.

  • https://[email protected] is a whole URL; slashes inside a path are not commands.

Markdown / HTML links

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

What happens when users tap @

  • Resolved real user → open that user’s profile (guest view).

  • Unresolved → search / toast along the lines of “user not found”, then return (about 3 seconds or manual dismiss, per client).

Related

Source of truth

Did this answer your question?