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.
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
@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.
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.
