Microsoft Teams Link Preview — How It Works & How to Fix It
When you paste a URL into a Microsoft Teams chat or channel, Teams automatically unfurls it into a rich preview card with a title, description, and image. If the preview is missing or wrong, here's how to diagnose and fix it.
How Microsoft Teams Reads Link Previews
Teams uses a server-side bot to fetch the URL and read its metadata. Teams checks, in order:
- Open Graph tags (
og:title,og:description,og:image) — the primary source - Twitter Card tags (
twitter:title,twitter:description,twitter:image) — used as fallback - Standard HTML (
<title>,<meta name="description">) — final fallback if neither OG nor Twitter Card tags are present
The Teams unfurl bot runs server-side and does not execute JavaScript. Tags must be present in the raw HTML response.
Common Reasons Teams Previews Fail
Missing Open Graph tags
Teams requires og:title at minimum. Without it, Teams may show only a raw URL with no preview card.
Page is not publicly accessible
Teams' unfurl bot cannot access pages behind Microsoft 365 authentication, VPNs, or other access controls — even within a Teams organisation. The URL must be reachable from the public internet for Teams to unfurl it.
Exception: Microsoft 365 SharePoint links and other internal Microsoft services are natively understood by Teams and bypass this requirement.
JavaScript-rendered meta tags
Teams does not run JavaScript. If your og: tags are injected client-side by React, Angular, or Vue, Teams won't see them.
og:image too small or inaccessible
Teams requires the image URL to be publicly accessible over HTTPS. Images smaller than ~200×200 px may be ignored.
Rate limiting or slow server responses
If your server is slow to respond or returns an error, Teams may skip the preview silently and cache the failure.
How to Fix Teams Link Preview
- Add Open Graph tags to your HTML
<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" />
- Verify they're server-rendered — open a terminal and run:
curl -s https://example.com/your-page | grep -i "og:"
If the tags don't appear in the output, they're being set by JavaScript and Teams can't read them.
Confirm the image is accessible — open your
og:imageURL in a private browser window. If it doesn't load, Teams can't fetch it either.Test with TryUnfurl — paste your URL at TryUnfurl to see the detected og: tags, image dimensions, and any issues — without needing to post in a real Teams channel.
Re-paste the link in Teams — Teams does not have a standalone cache-clearing tool. Paste the URL into a new chat or message to trigger a fresh unfurl. If the preview was missing before and you've now fixed the tags, the next paste should show the correct preview.
Teams vs. Slack: Key Differences
| Feature | Microsoft Teams | Slack |
|---|---|---|
| Reads og: tags | ✓ | ✓ |
| Reads Twitter Card tags | ✓ (fallback) | ✓ (fallback) |
| Executes JavaScript | ✗ | ✗ |
| Cache-clearing tool | None (re-paste) | / command + cache timeout |
| Internal URL unfurling | Via Teams app connectors | Via Slack apps |
| Image minimum size | ~200×200 px | ~80×80 px |
Frequently Asked Questions
Why does my Teams link preview show only a URL with no card?
This usually means og:title is missing or the unfurl bot couldn't reach your page. Check that your URL is publicly accessible and that og:title is set in the raw HTML (not JavaScript).
Does Teams cache link previews?
Yes. Teams caches unfurl results for a period that varies by client. Re-pasting the URL into a new message usually triggers a fresh fetch.
How do I unfurl internal company URLs in Teams?
Internal URLs behind authentication require a custom Teams app with messaging extension connectors. The public unfurl bot cannot access private networks.
Can I control which image Teams uses for a preview?
Yes — set og:image to your preferred image URL at 1200×630 px. Without an og:image tag, Teams will attempt to find images on the page, which produces unpredictable results.
My Teams app unfurls the link differently from web Teams — why?
The desktop app, web app, and mobile app may have slightly different caching and rendering behaviour. The og: tags control the data; any visual differences are rendering differences in the Teams client itself.
Does Teams support Open Graph for SharePoint pages?
SharePoint pages are treated as first-party Microsoft content and use a dedicated preview system in Teams, separate from the Open Graph unfurl bot.