Why Microsoft Teams Link Preview Images Are Not Showing and How to Fix Them
Learn why Microsoft Teams link preview images are missing or stale, how to diagnose the cause, and how site owners can fix metadata and image access.

Microsoft Teams can turn a pasted website URL into a preview card with an image, title, and description. When the image is missing or an old thumbnail remains, the cause is usually one of four things: the page or image cannot be fetched publicly, the page metadata is incomplete or incorrect, the Teams flow has specific preview requirements, or a cached preview has not refreshed yet.
Start by identifying whether the problem affects one URL or many. If you own the website, inspect its metadata and image URL. If you do not own it, compare another public link, try Teams web and desktop when available, and send the site owner the affected URL and what you observed. Microsoft’s documentation explains that Teams unfurls website links into Adaptive Cards containing information such as an image, title, and description. Microsoft’s Micro-Capability and Schema guidance also describes structured metadata that can support rich unfurls.
First, identify the symptom
| Symptom | Most useful first check | Who can fix it |
|---|---|---|
| No preview card at all | Check whether the page requires authentication and whether the URL is publicly reachable. | Usually the site owner; a Teams user can report it. |
| Card appears without an image | Inspect the image metadata and confirm the image URL loads without a login. | Site owner. |
| Old title or thumbnail | Confirm the new metadata is live, then allow time and retry. | Site owner and Teams service cache. |
| Only one person sees the problem | Compare Teams web and desktop and try a second URL. | Often client or cache related. |
| Several unrelated links fail | Compare clients, accounts, and network conditions. | May require Teams administration or Microsoft support. |
These comparisons are diagnostic checks, not a promise that every Teams client renders identically. They help separate a page problem from a client or service problem.
How Teams decides what to show
Teams reads information exposed by the website and uses it to build a link preview. Microsoft’s Share to Teams web-app guidance says a preview needs either a thumbnail image or both a title and description. That same guidance says a URL that requires authentication does not receive a preview in that flow, and recommends providing all three elements when possible: title, description, and thumbnail. Read the Share to Teams requirements.

For the documented Share to Teams flow, the supported Open Graph properties include:
<meta property="og:title" content="Your page title">
<meta property="og:description" content="A concise page description.">
<meta property="og:image" content="https://example.com/images/preview.jpg">
Keep these tags in the page’s HTML head. The image URL should be an absolute HTTPS URL that can be fetched without a session cookie, basic authentication, a VPN, or an expiring private token. The page itself should also be reachable by the service that creates the unfurl. A browser where you are already signed in can load a resource that an unauthenticated preview fetcher cannot.
Open Graph and Schema.org are related but not interchangeable
Open Graph tags describe the title, description, and image used by the documented Share to Teams flow. Microsoft’s Micro-Capability and Schema documentation covers Schema.org metadata and JSON-LD for richer website-link unfurls. Use the format required by the Teams feature you are implementing, and validate the actual public URL after publishing. Do not assume that adding JSON-LD alone will repair an Open Graph image problem.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "WebPage",
"name": "Your page title",
"description": "A concise page description.",
"image": "https://example.com/images/preview.jpg"
}
</script>
Microsoft recommends validating website-link structured data before pasting the link into Teams. Validation confirms what your page publishes; it does not guarantee that every client will show the same card.
Step-by-step fix for site owners
1. Confirm the intended image is in the live HTML
Open the public page in a private browser window, view its source, and search for og:image. Check that the value is the image you expect, not a staging asset, an old CDN path, or a relative URL. If your framework generates metadata, inspect the final rendered response rather than only the template.
2. Test the image URL independently
Paste the image URL into a private browser window. It should return the image without a login, cookie, JavaScript challenge, or special referer. Check redirects as well: a chain that ends at a blocked or expired URL can prevent the thumbnail from loading.
curl -I "https://example.com/images/preview.jpg"
# Follow redirects and show the final response headers
curl -IL "https://example.com/images/preview.jpg"
Look for a successful HTTP response, an image content type such as image/jpeg, image/png, or image/webp, and a URL that remains publicly accessible. A 401 or 403 response, a redirect to a sign-in page, or a server rule that blocks automated fetches can explain a missing image.
3. Provide all three preview fields
Even when an image is the main goal, include og:title, og:description, and og:image. The Share to Teams guidance documents a thumbnail or the combination of title and description as the minimum preview paths; supplying all three gives the card enough fallback information.
<head>
<meta property="og:title" content="Why link previews fail">
<meta property="og:description" content="A practical troubleshooting guide.">
<meta property="og:image" content="https://example.com/previews/link-preview.jpg">
</head>
4. Publish the change on the canonical URL
Verify that the URL you paste into Teams is the same URL whose metadata you edited. Redirects, language variants, tracking links, and canonical URLs can make you inspect one document while sharing another. If the page redirects, inspect the final public page too.
5. Validate structured data when using Schema.org
Use Microsoft’s documented validation workflow for Schema.org or micro-capability metadata, correct any reported errors, and then test the website link in the Teams compose area. Validation is especially useful when a CMS or server-side renderer conditionally omits fields.
6. Re-test after the metadata is live
Paste the URL into a new compose box and compare the result with a second public URL. If the old image remains, allow time and retry. Microsoft’s reviewed documentation does not define a universal cache duration or a standard user-facing cache reset for ordinary website previews.
What users can do when they do not own the site
- Try a second public website link. If the second link previews correctly, the original site is the likely source of the problem.
- Try the affected link in Teams web and desktop if both are available. Record whether the symptom appears in one client or both.
- Check whether the page asks for a sign-in. In the documented Share to Teams flow, authentication-required URLs do not receive a preview.
- Send the site owner the exact URL, the missing or stale image you see, and the Teams client where it occurred. Ask them to check the page metadata and image URL.
You can also paste the URL into a private browser window. This does not reproduce Teams’ fetcher exactly, but it can reveal an obvious login wall, redirect loop, or unavailable image.
Stale thumbnails: what is known and what is not
A stale card usually means the service is still using an earlier fetch of the page or image. Microsoft Q&A discussions describe users waiting or adding a changed query parameter to the URL as possible workarounds. Those are individual reports, not Microsoft guarantees. The official guidance reviewed here does not establish a universal expiry time or a supported cache-clearing command.
If you must test a changed URL, treat it as a diagnostic experiment. For example, a site owner might share https://example.com/article?preview=2 after confirming that the parameter does not change page access or routing. Do not add parameters that expose private data, break analytics, or create a different canonical page. The durable fix remains correct, publicly accessible metadata on the intended URL.
Common errors and fixes
| Error or observation | Likely cause | Fix |
|---|---|---|
| Preview is absent for a private page | The page requires authentication. | Share a public URL or ask the site owner to provide an accessible page. The documented Share to Teams flow does not preview authentication-required URLs. |
| Image tag points to a relative path | The fetcher cannot resolve it as intended. | Use an absolute HTTPS URL in og:image. |
| Image URL returns 403 | CDN, WAF, hotlink, or referer rules block the request. | Allow public access to the preview asset and review security rules. |
| Image redirects to sign-in | The asset is protected even though the page is public. | Place a public preview copy at a stable URL. |
| Old image persists after a change | Cached metadata or image. | Confirm the live response, wait, retry, and document the URL and clients affected. Q&A workarounds are not guaranteed. |
| Title appears but image does not | Image metadata is missing, malformed, or unreachable. | Check og:image, its response headers, redirects, and public access. |
| Different clients show different cards | Client or service differences. | Record Teams web versus desktop behavior and escalate with the URL and metadata. |
| Preview works in a normal browser only | Your browser has cookies, a session, or network access unavailable to the preview fetch. | Test privately and remove authentication requirements from the preview resources. |
Capture and inspect the exact image your page exposes
When a page changes frequently, a screenshot can help you compare the visual result with the metadata you intended to publish. You can use browser automation locally, but it requires a browser runtime, navigation waits, cookie handling, and cleanup of overlays. For a repeatable capture, document the URL, viewport, wait condition, and timestamp alongside the saved image.
// Minimal Playwright example (Node.js)
import { chromium } from 'playwright';
const browser = await chromium.launch();
const page = await browser.newPage({ viewport: { width: 1200, height: 630 } });
await page.goto('https://example.com/article', { waitUntil: 'networkidle' });
await page.screenshot({ path: 'preview-check.png', fullPage: false });
await browser.close();
For an element-only check, replace the page screenshot with a locator screenshot:
const card = page.locator('main');
await card.screenshot({ path: 'main-element.png' });
Browser capture can still include cookie banners, newsletter popups, or chat widgets that obscure the content. It can also encounter bot checks, blank pages, timeouts, or failed resources. Those cases need explicit handling in your script.
Or skip the browser setup
ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. Before capture it accepts the cookie or consent banner like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server includes take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.

See the ScreenshotNeo API documentation for all options. A direct call looks like this:
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com/article -o shot.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)
open("shot.webp", "wb").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}`);
const bytes = await res.arrayBuffer();
await Bun.write('shot.webp', bytes);
ScreenshotNeo supports full-page capture with lazy images loaded, CSS-selector element capture, dark mode, 12 device presets or any viewport, retina scale, custom CSS and JavaScript, clicks before capture, hidden selectors, waits for selectors, delays or network idle, blocked ads and trackers, custom headers, cookies, user agents and Authorization, timezone and geolocation, transparent backgrounds, image resizing, chosen cache TTLs, signed links, async jobs with signed webhooks, bulk capture for up to 100 URLs per call, a usage API, and an OpenAPI specification. Existing parameter names used by other screenshot APIs also work, which can simplify migration.
For this Teams investigation, useful options include a 1200×630 viewport for a social-style preview, a selector for the article content, a wait for the headline or image selector, and custom CSS to hide elements that are not part of the intended preview. Cache intentionally when comparing stable pages; choose a short TTL while debugging metadata changes.
The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; Growth is $15 for 15,000, Pro $39 for 60,000, Scale $99 for 250,000, and Business $249 for 1,000,000. Yearly billing provides two months free, and every feature is on every plan. Create a free ScreenshotNeo account to capture your first 1,000 screenshots without a card.
Performance, reliability, and cost considerations
- Wait only as long as needed. Network-idle waits improve accuracy for pages with deferred images but increase latency. A specific selector wait is often more predictable.
- Use element capture when full-page output is unnecessary. It reduces image size and focuses comparison on the metadata-driven content.
- Control caching deliberately. A cache TTL helps repeated checks, while a short TTL is better immediately after changing Open Graph tags.
- Separate failures from billable clean captures. ScreenshotNeo returns verdict and billing headers, so your job can record whether a result was clean, failed, blank, blocked, or a cache hit.
- Use async jobs for batches. Signed webhooks avoid keeping a request open while processing many URLs; bulk capture supports up to 100 URLs per call.
- Protect credentials. Keep API keys server-side, use signed links for public image tags, and pass authorization headers only when the target page requires them.
FAQ
Does Teams always use Open Graph?
The documented Share to Teams flow lists Open Graph title, description, and image properties. Microsoft also documents Schema.org micro-capabilities for rich website-link unfurls. Use the metadata format for the specific Teams feature you are integrating.
What image dimensions does Teams require?
The reviewed Microsoft guidance does not specify a universal required dimension. Use a clear, publicly reachable image and verify the final card in your target Teams client.
Can I force Teams to refresh a thumbnail?
There is no universal refresh command or cache lifetime established by the official guidance reviewed here. Waiting and trying a changed query parameter are anecdotal Q&A suggestions, not guarantees.
Why does a link work for me but not colleagues?
Your browser may have authentication cookies or network access that the preview fetcher and colleagues do not. Test the page and image in a private window and check whether the URL is public.
Should I remove all security controls from my site?
No. Keep normal security controls and publish a deliberately public preview page and image when a public Teams unfurl is required. Review CDN and WAF rules narrowly rather than disabling protection broadly.
Can ScreenshotNeo generate a Teams-specific card?
ScreenshotNeo captures the rendered website as an image or PDF. It does not replace Teams’ metadata unfurling; it helps you inspect and archive the visual page that visitors receive.


