
How does Telegram build a link preview?
Telegram added rich link previews in April 2015. Its announcement describes the behaviour that still holds: once you paste a URL into the message input field, Telegram starts analyzing the link and getting a preview for it, and if you would rather send the message without the preview you tap the x to remove it.
The result is stored as a webPage object in Telegram's API. Its fields read like a list of Open Graph properties: site_name, title, description, photo, author, duration, plus an embed_url with width and height for players. The object also carries a hash that the documentation says is used for caching. Telegram does not publish which HTML tags fill which field, so the safe course is a complete set of standard tags, set up as described in adding Open Graph tags to WordPress.
What kinds of preview can Telegram show?
The webPage object has a type that changes how the card is drawn. For ordinary sites, three of the documented types matter.
| webPage type | What Telegram's docs say | What it means for your page |
|---|---|---|
| article | Preview of a generic external article or webpage; if a cached Instant View page exists, clients add an Instant View button | The normal card for a blog post or product page |
| photo | Preview of an external photo, held in the photo field | A direct link to an image file |
| profile | Preview of an author or profile page, typically drawn with a small thumbnail (forced small media) | Author and profile pages get a small image no matter what you supply |
There is also a has_large_media flag that marks whether the media size in a preview can be changed. Telegram does not publish an image size that triggers the large layout, so use the dimensions in our Open Graph image size guide and check the result in the app.
Test your Telegram link preview
Saved Messages is your private chat with yourself, which makes it the quietest place to test.
Open Saved Messages
In the Telegram app, find Saved Messages in your chat list, or search for it by name.
Paste the full URL
Paste the exact address you plan to share, with https. Do not press send yet.
Wait for the card
Telegram analyzes the link and shows the preview above the input field. Check the site name, the title, the description and the image.
Compare with your source
Open your page source and confirm the title and image match your
og:titleandog:image. A mismatch points to a duplicate tag or a cached page on your side.Send or remove
Send to keep a record, or tap the x on the card to drop the preview and send plain text, as Telegram's announcement describes.
Check on a second device
Open the same message on your phone and on desktop. Clients can draw the card at different widths, so make sure the title still reads well when it is cut short.
If the card looks wrong before you even reach Telegram, paste your page's HTML into our free source-based preview checker. It reads the tags in your browser and fetches nothing, so you can fix a draft before it is public.
How do I refresh an old Telegram preview?
Telegram's public documentation, as checked in November 2026, does not describe a tool site owners can use to clear a cached preview. The webPage object has a caching hash, but that is for Telegram's own clients and servers, not something you can reset from outside.
What you can do: fix the tags on your site, purge your page cache and CDN for that URL, and if you changed the image, upload it under a new file name so any cache keyed on the old image URL is skipped. Then paste the URL into a fresh message. Messages already sent keep the card they were built with, the same pattern described in the WhatsApp and Apple Messages guide.
Link preview options for bots and channels
If you post to a Telegram channel through a bot, you control the preview per message. The Bot API's LinkPreviewOptions object has five optional fields.
| Field | Type | What it does |
|---|---|---|
| is_disabled | Boolean | True turns the link preview off for that message |
| url | String | The URL to preview; if empty, the first URL in the message text is used |
| prefer_small_media | Boolean | Asks for shrunk media; ignored if url is not set or the size cannot change |
| prefer_large_media | Boolean | Asks for enlarged media; same conditions as above |
| show_above_text | Boolean | True puts the preview above the message text instead of below |
{
"chat_id": "@example_channel",
"text": "New guide: fixing the town clock https://example.com/town-clock/",
"link_preview_options": {
"url": "https://example.com/town-clock/",
"prefer_large_media": true,
"show_above_text": true
}
}Set url explicitly whenever the message contains more than one link, otherwise Telegram previews the first one it finds, which may be a tracking link or a sponsor rather than your article.
What is Instant View?
Instant View is a separate, reader-mode page that opens inside Telegram. According to Telegram's Instant View intro, when a link preview is generated the Instant View bot checks for a template for that site; if one exists, it builds a lightweight copy of the article that is cached on Telegram's servers, and users see an Instant View button. Webmasters do not need to change anything for it to work.
Templates are written in Telegram's Instant View Editor. A template has to be approved by the Telegram team before all users see it, but a site owner can share t.me/iv?url=...&rhash=... links in their own channel straight away. For most WordPress sites this is optional; the ordinary card is what matters.
What goes wrong
- Tags written by JavaScript. Build tags on the server. A preview fetcher reads the HTML it receives.
- A relative og:image path. Use a full https address so the fetcher can load the file from outside your site.
- A page Telegram treats as a profile. Telegram documents that profile previews are drawn with a small thumbnail, so a large image will not change them.
- Several links in a bot post. Without
link_preview_options.url, the first link wins. - A security rule that challenges unknown visitors. The preview shows the challenge page title instead of yours.
- Expecting sent messages to change. Edits to your tags affect new messages only.
Check it worked
- A fresh paste into Saved Messages shows your title, description, image and site name.
- The image matches the file in your
og:imagetag, not a logo or a random picture from the page. - The card reads well on both phone and desktop clients.
- Bot posts show the preview for the URL you set, in the position you chose.
- If your site has an Instant View template, the Instant View button appears on article links.
For the wider picture of how each network reads these tags, start at the link previews hub.
Sources
- Telegram Blog, Link Previews (April 8, 2015)
- Telegram API documentation, webPage constructor (fetched November 2026)
- Telegram Bot API, LinkPreviewOptions (fetched November 2026)
- Telegram, Instant Views Explained (fetched November 2026)
Questions
How do I test a Telegram link preview?
Paste the full URL into Saved Messages, your private chat with yourself, and wait for the card to appear above the input field before sending. Check the title, description, image and site name against the Open Graph tags in your page source.
How do I remove a link preview in Telegram?
Tap the x on the preview card before sending. Telegram's own announcement of link previews describes this. Bots can do the same per message by setting is_disabled to true in LinkPreviewOptions in the Bot API.
Does Telegram use Open Graph tags?
Telegram does not publish which tags it reads. Its webPage object has fields named site_name, title, description and photo, which mirror Open Graph properties, so a complete set of og tags is the reliable way to control the card.
Can I force Telegram to refresh a cached preview?
Telegram's documentation does not describe a public refresh tool. Fix your tags, purge your page cache, rename a changed image file, and paste the link into a new message. A bot called @WebpageBot exists, but Telegram does not document what it does.
What is the difference between a link preview and Instant View?
A link preview is the small card under a message. Instant View is a full reader-mode copy of an article that opens inside Telegram, built from a template and cached on Telegram's servers. It appears only for sites with an approved template.
Hannah Voss, Editor. Checks every guide against a working WordPress install and the networks' current documentation. Last reviewed September 2026.
Related reading
- Open Graph image size: 1200 by 630 and the safe zoneThe right Open Graph image size is 1200 by 630 pixels at a 1.91:1 ratio. Minimums, file limits, formats, and a centre safe zone for square crops.6 min read
- Adding Open Graph tags in WordPressAdd Open Graph tags to WordPress with an SEO plugin or theme code: the four required tags, image tags, per-post overrides, and how to avoid duplicate tags.7 min read
- WhatsApp and iMessage link previews: how they are built and how to fix themHow WhatsApp and Apple Messages build link previews from your Open Graph tags, the image sizes each documents, how to test, and why a preview is missing.9 min read
- Link preview checker: test your Open Graph and card tagsPaste a page's HTML to check its Open Graph and X card tags, see mock previews, and find duplicate, missing or relative tags. Runs in your browser only.10 min read