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, orsendAnimation.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_idreuse is not supported — use HTTPS URL or multipart upload.
MessageEntity: two @ styles
Raw
@usernamein text: when you omitentities, the server may auto-resolve unique usernames to mentions.Explicit
entitieswithtype: "text_mention"+user.id: visible text can be any label, anchored to that user id (group member validation applies).Today, public
entitiesinput supports onlytext_mention. Do not combine withweb_appentry 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
Core message methods (sendMessage, entities, link_preview_options)
Inline keyboard guide
User-facing: link preview cards in chat
