TryUnfurl

Check How Your Links Unfurl for FREE!

See exactly how your webpage will appear when shared on social media, Slack, Discord, and messaging apps.

Try It Now →

Telegram Link Preview Not Working — How to Fix It

When you share a URL in a Telegram chat or channel, Telegram's servers fetch the page and generate a preview card with a headline, description, and image. When the URL unfurl shows only the raw URL, the wrong image, or nothing at all, the cause is almost always on your page — usually a missing Open Graph tag, an inaccessible image, or JavaScript-rendered metadata that Telegram's crawler can't see.

This guide covers the Telegram URL unfurl process end-to-end, the most common reasons a Telegram link preview fails, step-by-step debugging, how to test your URL unfurl before sending, and the advanced Open Graph optimizations that make Telegram previews render consistently for channels and chats.

→ Test your Telegram link preview with TryUnfurl

Understanding URL Unfurling in Telegram

Telegram uses a server-side bot (TelegramBot) to fetch URLs and extract metadata. Every time you paste a link — in a private chat, a group, or a channel — the same preview generation pipeline runs:

  1. TelegramBot fetches your URL server-side, with no browser, no JavaScript execution, and a generic TelegramBot user-agent.
  2. Telegram parses the HTML <head> in this priority order:
    • Open Graph tags — og:title, og:description, og:image
    • Twitter Card tags — twitter:title, twitter:image (used as fallback)
    • <title> tag — final fallback for the headline
  3. Telegram renders a preview card with the extracted title, description, and image.
  4. The URL unfurl is cached per URL, so subsequent shares of the same link serve the cached card.

Like all major messaging platforms, Telegram's preview bot does not execute JavaScript. All meta tags must be present in the raw HTML response for Telegram URL unfurl to work.

Common Reasons Telegram Link Previews Fail

1. Missing og:title or og:image

Telegram requires at least og:title to generate a preview card. Without it, only the bare URL is shown. Without og:image, the preview renders text-only — no thumbnail.

2. Image format not supported

Telegram supports JPEG and PNG for preview images. WebP and GIF are not reliably rendered. Use JPEG for photos and PNG for graphics.

3. Image file is too large

Very large images (over 5 MB) may be skipped by Telegram's fetcher. Keep preview images under 1 MB at 1200×630 px.

4. Page requires JavaScript to render

Telegram's bot reads raw HTML. JavaScript-injected meta tags are invisible to it. Open Graph tags must be in the server-sent HTML, not injected by React, Vue, or Angular.

5. Blocked server or geo-restriction

If your server blocks Telegram's crawl-bot IPs or returns different content based on user-agent, the preview will fail. Telegram's bot uses a generic TelegramBot user-agent — make sure your server responds normally to it.

6. Telegram cached a failed fetch

Telegram caches both successful previews and failed fetches. Once a URL fails, Telegram may not retry for hours. The fix: append a query-string cache-buster (?v=2) when re-sharing.

7. Missing or wrong Content-Type

If your page is served with Content-Type: application/json or something other than text/html, Telegram may refuse to parse it for meta tags.

Step-by-Step Telegram Preview Debugging

Step 1 — Add Open Graph tags to your <head>

<meta property="og:title" content="Your Page Title" />
<meta property="og:description" content="A concise description." />
<meta property="og:image" content="https://example.com/preview.jpg" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:url" content="https://example.com/your-page" />
<meta property="og:type" content="website" />
<meta property="og:site_name" content="Your Site Name" />

Step 2 — Confirm server-rendering

Check what the raw HTML response actually contains:

curl -sL -A "TelegramBot (like TwitterBot)" https://example.com/your-page | grep -iE '<meta (property|name)="(og|twitter)'

If the tags don't appear in the output, they're JavaScript-injected and invisible to Telegram. Switch to SSR, SSG, or pre-rendering.

Step 3 — Check image format, size, and accessibility

Step 4 — Test with TryUnfurl

Paste your URL into TryUnfurl to validate your Open Graph tags and see exactly what Telegram's bot will read — without posting in a real Telegram chat. You'll also see how the same URL unfurl looks on Facebook, LinkedIn, X, Slack, Discord, iMessage, WhatsApp, and Teams, which helps catch cross-platform inconsistencies in one view.

Step 5 — Force a fresh preview

Telegram does not expose a public cache-clearing tool. To force a refresh, append a dummy query string (e.g. ?v=2 or ?ref=tg) to the URL when re-sharing. Telegram treats this as a new URL and fetches it fresh.

Testing Your URL Unfurl Results

Before posting a link in a high-value Telegram channel — a community announcement, a product drop, a paid subscriber post — confirm the URL unfurl renders correctly with a multi-platform link preview checker.

TryUnfurl gives you:

For launches or migrations with many URLs, the bulk URL unfurl checker runs up to 100 URLs in one pass and exports results as CSV.

Advanced Open Graph Optimization for Telegram

Once the basics are right, these extra moves keep Telegram URL unfurl cards crisp across channels and clients:

Telegram Preview vs. Instant View

Telegram also has an Instant View feature that opens articles directly inside the Telegram app without opening a browser. Instant View uses a separate template system (configured via Telegram's Instant View editor) and is distinct from the basic link preview card.

The link preview card (title + description + image) is controlled by Open Graph tags. Instant View is a richer reading experience and requires a separate setup — useful for publishers and content-heavy sites, not required for most link-sharing use cases.

Frequently Asked Questions

Why does my Telegram preview only show a URL with no card?

This usually means og:title is missing from the raw HTML, or Telegram's bot couldn't reach your page. Check server accessibility and that og:title is present in the server-rendered HTML — not injected via JavaScript.

How do I refresh a Telegram link preview cache?

Telegram has no public cache-clearing endpoint. The cleanest workaround is to append a query parameter to the URL when sharing (e.g. ?v=2 or ?ref=tg). Telegram treats this as a new URL and fetches it fresh.

Does Telegram show link previews for all URLs?

Telegram generates previews for public URLs. It respects X-Frame-Options and some server-side signals, but the main requirement is that the page is publicly accessible and has Open Graph tags.

Does Telegram support Twitter Card tags?

Partially. Telegram may read twitter:image as a fallback if og:image is absent, but this behaviour is not guaranteed. Always set Open Graph tags explicitly.

Why does my preview image show in X/Twitter but not Telegram?

X's Card Validator and Telegram's bot use different crawlers with different user-agents and caching layers. If your server responds differently based on user-agent, that's usually the cause. Use TryUnfurl to simulate platform crawlers against your URL.

Can Telegram show animated GIF previews?

Telegram's link preview card does not support animated GIFs as the og:image. Use a static JPEG or PNG.

How do I test a Telegram URL unfurl without posting in a chat?

Paste the URL into TryUnfurl. It renders the preview card using the same Open Graph tags Telegram reads, without requiring you to send a message.

Related Guides

For more information, visit “What is Unfurling?”, our complete guide to link previewing on the internet and social media.