How to Make a Website Link Preview Show the Right Image in Telegram Channels

To make a website link preview show the right image in a Telegram channel, first make sure the exact page URL returns the intended preview image and description in its HTML, and that the image URL is reachable by Telegram’s fetcher. Then check Telegram’s preview controls and determine whether the problem is the page data, preview generation, or how a client displays the preview. Correct metadata helps, but Telegram’s reviewed public documentation does not define a complete external-page crawler specification or guarantee that metadata changes will refresh a preview.

This guide distinguishes what Telegram documents from practical checks for site owners, developers, editors, and channel administrators. It also shows how to inspect the rendered page and image with ScreenshotNeo, a website screenshot API and MCP server from ScreenshotNeo. A screenshot helps you see what a visitor sees; inspect the returned HTML and server requests as well, because a visual capture alone cannot establish which metadata Telegram fetched.

1. Understand which part controls the image

A link preview has two sides: information associated with the webpage and controls that affect how a message displays its preview. Telegram’s WebPage type includes a photo representing the content. TDLib describes preview information such as site name, title, description, author, and type. The documented model explains the fields in a preview, but does not establish a universal HTML-tag precedence rule for external websites. Telegram WebPage constructor · TDLib WebPage reference

TDLib also offers message-level preview options: a preview can be disabled, generated from a selected URL, displayed with small or large media, or placed above the message text. These options change selection or presentation; they do not set the website’s image metadata. TDLib link preview options

2. Fix the website data first

Use the exact URL being shared. Check the page after redirects, including its canonical host, path, and query string when relevant. Different URL variants may be handled as different inputs.
Inspect the HTML response. Review the HTML returned for that URL, not only the page after JavaScript runs. Confirm that the page’s preview metadata points to the intended article image and that its title and description describe this page. Telegram’s general preview references describe the resulting fields but do not give a definitive HTML recipe or tag precedence.
Choose a page-specific image. Prefer a representative article or page image over a generic site logo when the page has a suitable cover. Telegram’s Instant View checklist recommends a suitable photo, a description, and a site name matching the name visible on the website. This checklist concerns Instant View authoring; it is useful guidance, not a full specification for external previews. Telegram Instant View checklist
Check image reachability. The image must be retrievable by the preview fetcher. Inspect its response, redirects, access restrictions, and server logs where available. Compare behavior for the page and image requests rather than assuming that a browser can load them in every crawler context.
Publish and verify. After updating the page, request the exact shared URL in Telegram and inspect the resulting card. Record the URL and time. Do not assume a particular cache duration or a universal cache-busting or refresh procedure: the reviewed official references do not specify one.

What to check in the returned HTML

Find the page’s preview-related metadata and verify that the image reference is the intended one, the title and description are page-specific, and the image address resolves to the expected asset. If your site renders metadata with JavaScript, check the original HTTP response separately; browser-rendered DOM content may not be the same content a fetcher receives. The cited Telegram references do not say which specific HTML tag wins when multiple tags conflict, so remove contradictory values and serve one consistent intended set rather than relying on undocumented precedence.

3. Inspect the exact page and image

A browser screenshot can reveal a wrong page variant, a consent overlay, a blank render, or a page that looks different from what you expected. ScreenshotNeo can capture the page, but use your HTTP inspection and server logs for metadata and crawler-request evidence.

With a ScreenshotNeo API key, the following calls capture the exact page as a WebP image. Replace the URL with the page you share. The API accepts one GET request with a URL and can return PNG, JPEG, WebP, or PDF; its broader capture options include full-page capture, custom headers and cookies, wait conditions, and CSS or JavaScript customization. See the ScreenshotNeo API documentation for parameters.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://example.com/article \
  -o telegram-preview-check.webp

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={
        "access_key": "YOUR_API_KEY",
        "url": "https://example.com/article",
    },
    timeout=90,
)
r.raise_for_status()
with open("telegram-preview-check.webp", "wb") as image:
    image.write(r.content)

Node.js

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com/article',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs =>
  fs.writeFile('telegram-preview-check.webp', image)
);

Do not put a private API key in browser code or a public page. If a page requires authentication, use an authorized capture configuration and protect any supplied credentials. A screenshot shows the rendered page at capture time; it does not prove Telegram fetched the same HTML, selected the same image, or cached the same result.

4. Diagnose a wrong or missing preview

Symptom	Check	Next step
Telegram shows the wrong image	Inspect the exact URL’s returned HTML and image address. Check whether the shared URL redirects to a different page.	Make the page’s preview information consistent and point it at the intended page-specific image. Request the exact URL again and record the result.
Telegram shows no card	Check whether the message’s preview is disabled, whether the intended URL is selected, and whether the page and image are reachable.	Enable the preview in the client or library when applicable; inspect server logs for requests and compare the page’s response with a normal browser request.
The card is old after a site update	Verify the new HTML and image at the exact URL first. Record when Telegram was asked to generate the preview.	Request the URL again and observe the outcome. Telegram’s reviewed general documentation does not publish a cache lifetime or guarantee a refresh workflow.
It works for one URL or client but not another	Compare URL variants, client/version, attempt time, and server requests.	Keep each observation separate. Reports in Telegram’s bug tracker describe variable outcomes, but do not establish a universal cause or fix. Telegram bug tracker
The page looks correct in a browser but Telegram is wrong	Compare the original HTML response with the browser-rendered page; check whether metadata is only added by scripts.	Serve the intended preview data in the HTML response and confirm the image can be fetched without a browser session.

Keep a useful diagnostic record

Exact URL sent in the channel, including redirects and relevant query parameters.
Time of the attempt and Telegram client/version where known.
HTML response and image URL served at that time.
Web server or CDN logs showing whether page and image requests arrived.
Whether another attempt, URL variant, or client produced a different card.

Bug reports can help show that fetch and display behavior is uncertain: users have reported cases where page or image requests appeared in logs but the preview was missing, and cases where a request did not appear. Treat these as diagnostic examples, not proof of a platform-wide rule. Telegram bug tracker

5. Telegram preview controls and Instant View guidance

If you publish through a client or library that exposes TDLib preview options, check whether the preview is disabled, whether another URL is selected for generation, whether media is forced to small or large size, and whether the preview is positioned above the text. These settings affect the message or client presentation. They cannot correct incorrect webpage metadata. TDLib link preview options

For Instant View authoring, Telegram’s checklist says to include a photo when a suitable image or document exists, provide a description, use a short source description when available, and make the site name match the visible website name. Keep that scope clear: Instant View guidance is not a promise about every ordinary external link preview. Instant View checklist

6. Limits and facts Telegram does not settle

The reviewed general preview documentation does not establish universal image dimensions, supported formats, file-size limits, a cache duration, or a guaranteed refresh method for ordinary external webpage previews. Avoid treating a specific dimension, format, cache-busting query, or waiting period as an official requirement unless you have a current Telegram source that says so. Make the image publicly retrievable and appropriate to the page, then verify actual outcomes.

7. Performance, reliability, and cost

For site owners, the practical reliability work is to serve the intended metadata in the initial HTML and make the image consistently retrievable. Keep the diagnostic record when results vary. Telegram’s public references reviewed here do not provide preview-generation timing, retry guarantees, cache TTL, or a service-level promise for this scenario, so avoid basing a publication workflow on an assumed refresh interval.

ScreenshotNeo can help you inspect the rendered page without maintaining a browser automation setup. Its plans are Free: 1,000 shots/month with no card; Starter: $5 for 3,000; Growth: $15 for 15,000; Pro: $39 for 60,000; Scale: $99 for 250,000; Business: $249 for 1,000,000. Yearly billing gives two months free, and every feature is available on every plan. ScreenshotNeo bills only clean shots: bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing; each response reports the page verdict and billing status in headers. Those billing rules are ScreenshotNeo’s, not Telegram’s.

Or skip the browser setup

Use the one-call ScreenshotNeo request above to capture the page you are sharing. Cookie and consent banners are accepted and removed before the shot, along with known newsletter popups and chat widgets; each step can be turned off. Bot checks, blank pages, failed loads, and cache hits are never billed. An MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. The capture helps inspect what rendered; verify Telegram’s chosen card separately.

FAQ

Does correct page metadata guarantee the right Telegram image?

No guarantee is established in the reviewed Telegram references. Correct, reachable page data is the sensible first fix, followed by checking what Telegram actually generates.

Does Telegram document a universal image size or cache expiry?

Not in the general preview documentation reviewed for this guide. Do not present a specific dimension or expiry as a universal Telegram requirement.

Can channel administrators change the website’s preview image from the post controls?

TDLib controls can affect preview generation selection or display, but the webpage’s data determines what image the site offers. A message option is not a substitute for fixing the page.

Will a screenshot tell me what Telegram’s crawler fetched?

No. A screenshot records a rendered capture. Inspect the HTTP response and server logs to investigate what the preview fetcher could reach.