Webpage preview
The type field indicates the type of the web page, which influences how the preview is rendered (i.e. which extra action button is offered, where the media is taken from, and which WebPageAttribute is present in the attributes field). It can be one of the following:
app - Preview of a Mini App link »: the photo is the app icon, and clients render a button that launches the Mini App ».article - Preview of a generic external article or webpage. If cached_page is set, clients render an instant view button.document - Preview of an external document or file, contained in the document field.gif - Preview of an external animated GIF. If embed_url+embed_type are set the GIF is rendered using an embedded player, otherwise the animation is contained in the document field.photo - Preview of an external photo, contained in the photo field.profile - Preview of an external author or profile page; clients typically render this with a small thumbnail (forced small media).telegram_aicomposetone - Preview of an AI compose tone link », shared when previewing a custom AI composer tone ». The attributes field contains a webPageAttributeAiComposeTone with the custom emoji » representing the tone; clients render a button that applies the shared tone.telegram_album - Preview of a message link » pointing to a group of messages (album), rendered as a grouped media album rather than as a single-media preview. For this type the album media is not taken from the top-level photo/document fields: instead, a cached_page (instant view) must be present, and clients render the items of its first pageBlockCollage or pageBlockSlideshow block. Each pageBlockPhoto/pageBlockVideo item in that block references a photo or video by ID, resolved against the photos and documents of the cached_page. The instant view itself is not offered as a button (the album media replaces it).telegram_auction - Preview of an auction link » to a collectible gift auction ». The attributes field contains a webPageAttributeStarGiftAuction with the auctioned gift and the auction end date; clients render a button to join the auction, or to view the results once the auction has ended.telegram_background - Preview of a wallpaper deep link » to a chat wallpaper ». The wallpaper settings (background colors, gradient rotation, pattern intensity, blur/motion, etc.) are parsed from the deep link in the url, not from dedicated fields. Image wallpapers carry the wallpaper image in the document field. Pattern wallpapers also use the document field, with application/x-tgwallpattern or image/png as the pattern MIME type; the colors from the url are rendered as the pattern background and tint. Solid-color and gradient wallpapers carry no media and are rendered from the colors encoded in the url. No photo is present. Clients render a button to apply the background.telegram_bot - Preview of a bot link », rendered like a profile preview using the bot's avatar in the photo field.telegram_botapp - Preview of a direct Mini App link » to a named bot Mini App: the photo is the app preview, and clients render a button that opens the Mini App.telegram_call - Preview of a conference link » to a group call/conference call »; clients render a button to join the call (no photo/document is present).telegram_channel - Preview of a public username link » to a channel, using the channel's avatar in the photo field; clients render a button to open/join the channel.telegram_channel_boost - Preview of a boost link » to boost a channel », using the channel avatar in the photo field; clients render a button to boost the channel.telegram_channel_direct - Preview of a monoforum link » to the direct messages of a channel, using the channel avatar in the photo field.telegram_channel_request - Preview of a chat invite link » to a channel that has join requests » enabled; clients render a "Request to join" button.telegram_chat - Preview of a public username link » to a basic group, using the group avatar in the photo field; clients render a button to open/join the group.telegram_chat_request - Preview of a chat invite link » to a group that has join requests » enabled; clients render a "Request to join" button.telegram_chatlist - Preview of a chat folder link » to a shareable chat folder » (no photo/document is present): clients use the site_name, title and description fields for the preview text, no WebPageAttribute is required, and the action button opens the deep link in url to import the folder.telegram_collection - Preview of a gift collection link » to a gift collection ». The attributes field contains a webPageAttributeStarGiftCollection with the collection's icon stickers; clients render a button to view the collection.telegram_community - Preview of a chat folder link » to a shareable chat folder », rendered like telegram_chatlist.telegram_giftcode - Preview of a premium giftcode link » to a Telegram Premium gift code »; clients render a button to view/redeem the gift code (no photo/document is present).telegram_group_boost - Preview of a boost link » to boost a supergroup », using the supergroup avatar in the photo field; clients render a button to boost the supergroup.telegram_livestream - Preview of a video chat/livestream link » to a live video stream », rendered as a video chat preview marked as a livestream; clients render a button to watch the stream.telegram_megagroup - Preview of a public username link » to a supergroup, using the supergroup avatar in the photo field; clients render a button to open/join the supergroup.telegram_megagroup_request - Preview of a chat invite link » to a supergroup that has join requests » enabled; clients render a "Request to join" button.telegram_message - Preview of a message link » to a single message; clients render a button to open the message. Any cached_page instant view is ignored for this type.telegram_newbot - Preview of a managed bot creation request link » used to create a new bot; clients render a button to create/register the managed bot.telegram_nft - Preview of a collectible gift link » to a collectible (unique) gift ». The attributes field contains a webPageAttributeUniqueStarGift with the unique gift; clients render a button to view the collectible.telegram_stickerset - Preview of a stickerset link » to a sticker or custom emoji set ». The attributes field contains a webPageAttributeStickerSet with a few preview stickers and the emojis/text_color flags; clients display the preview stickers and render a button to view the sticker set (or custom emoji set, if the emojis flag is set).telegram_story - Preview of a story link » to a story ». The attributes field contains a webPageAttributeStory with the story's peer and ID (and optionally the embedded storyItem); the preview media and caption are taken from the story, and clients render a button to view it.telegram_story_album - Preview of a story album link » to a story album »: a photo (and optional video document) cover is present, and clients render a button to view the story album.telegram_theme - Preview of a theme link » to a theme ». The attributes field contains a webPageAttributeTheme with the theme file(s) and theme settings; clients render a button to apply the theme.telegram_user - Preview of a public username link » to a user, rendered like a profile preview using the user's avatar in the photo field.telegram_videochat - Preview of a video chat/livestream link » to a video chat », rendered as a video chat preview.telegram_voicechat - Preview of a video chat/livestream link » to a voice chat », rendered as a (non-video) video chat preview; clients render a button to join the voice chat.video - Preview of an external video. If embed_url+embed_type are set the video is rendered using an embedded player, otherwise the video is contained in the document field.webPage#e89c45b2 flags:# has_large_media:flags.13?true video_cover_photo:flags.14?true id:long url:string display_url:string hash:int type:flags.0?string site_name:flags.1?string title:flags.2?string description:flags.3?string photo:flags.4?Photo embed_url:flags.5?string embed_type:flags.5?string embed_width:flags.6?int embed_height:flags.6?int duration:flags.7?int author:flags.8?string document:flags.9?Document cached_page:flags.10?Page attributes:flags.12?Vector<WebPageAttribute> = WebPage;| Name | Type | Description |
|---|---|---|
| flags | # | Flags, see TL conditional fields |
| has_large_media | flags.13?true | Whether the size of the media in the preview can be changed. |
| video_cover_photo | flags.14?true | Represents a custom video cover. |
| id | long | Preview ID |
| url | string | URL of previewed webpage |
| display_url | string | Webpage URL to be displayed to the user |
| hash | int | Hash used for caching, for more info click here |
| type | flags.0?string | Type of the web page, which influences how the preview is rendered (i.e. which extra action button is offered, where the media is taken from, and which WebPageAttribute is present in the attributes field). See above for the list of possible values. |
| site_name | flags.1?string | Short name of the site (e.g., Google Docs, App Store) |
| title | flags.2?string | Title of the content |
| description | flags.3?string | Content description |
| photo | flags.4?Photo | Image representing the content |
| embed_url | flags.5?string | URL to show in the embedded preview |
| embed_type | flags.5?string | MIME type of the embedded preview, (e.g., text/html or video/mp4) |
| embed_width | flags.6?int | Width of the embedded preview |
| embed_height | flags.6?int | Height of the embedded preview |
| duration | flags.7?int | Duration of the content, in seconds |
| author | flags.8?string | Author of the content |
| document | flags.9?Document | Preview of the content as a media file |
| cached_page | flags.10?Page | Page contents in instant view format |
| attributes | flags.12?Vector<WebPageAttribute> | Webpage attributes |
How to transfer large data batches correctly.
How to fetch results from large lists of objects.
Webpage attributes
Telegram clients must handle special tg:// and t.me deep links encountered in messages, link entities and in other apps by registering OS handlers.
Bots can offer users interactive HTML5 web apps to completely replace any website.
Telegram offers many AI features powered by Cocoon — a decentralized network designed to maximize privacy.
Webpage attribute attached to a webPage of type telegram_aicomposetone, generated when previewing a shared AI composer tone » via an AI compose tone link ».
Telegram allows including animated and static custom emojis inside of messages.
Collage of media
Slideshow
A photo
Video
New collectible gift releases are distributed through Stars auctions held over several rounds.
Contains info about a collectible gift auction » for a webPage preview of an auction » (the webPage will have a type of telegram_auction).
Telegram apps support generating, sharing and synchronizing chat backgrounds.
How to start, join and manage group calls and video chats.
Telegram Premium users can grant their favorite channels and supergroups additional features like the ability to post stories by giving them boosts.
Chats and channels may have a public username or a private invite link: private invite links may be further enhanced with per-user join requests.
Telegram allows placing chats into folders, based on their type, mute status, or other custom criteria, thanks to folder blacklists and whitelists.
Users can send Gifts to their friends. The recipients of gifts can display them on their profile pages or turn them into Telegram Stars ». Telegram Stars can be used for many things, including supporting creators and buying services in mini apps.
Contains info about a gift collection » for a webPage preview of a gift collection » (the webPage will have a type of telegram_collection).
Telegram channel and supergroup administrators may launch giveaways to randomly distribute Telegram Premium subscriptions and other gifts among their followers, in exchange for boosts.
Contains info about collectible gift » for a webPage preview of a collectible gift » (the webPage will have a type of telegram_nft).
Telegram clients support displaying static and animated stickers.
Contains info about a stickerset », for a webPage preview of a stickerset deep link » (the webPage will have a type of telegram_stickerset).
Telegram users and channels can easily post and view stories through the API.
Webpage preview of a Telegram story
Represents a story.
Telegram apps support generating, sharing and synchronizing app themes.
Page theme