Microsoft Teams Link Preview — URL Unfurl Guide & Fix
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. When the URL unfurl doesn't render — or shows the wrong information — the cause is almost always one of a handful of predictable issues, and each has a straightforward fix.
This guide walks through the complete Teams URL unfurl process, every common reason Teams previews fail, step-by-step troubleshooting, the exact Open Graph tags Teams expects, testing your Teams link previews without posting in a real channel, and a FAQ for the trickier edge cases.
→ Test your Teams link preview with TryUnfurl
How the Teams URL Unfurl Process Works
Microsoft Teams runs the same URL unfurl pipeline every modern chat app runs — with a few Teams-specific details worth knowing.
- The Teams unfurl bot fetches your URL server-side, not from the user's client.
- It parses the HTML
<head>and reads metadata in this priority 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
- Open Graph tags (
- Teams renders a preview card using the extracted title, description, and image.
- The URL unfurl result is cached per URL.
Two Teams-specific characteristics:
- The unfurl bot does not execute JavaScript. Tags must be present in the raw HTML response.
- Teams only unfurls public URLs. The bot cannot reach pages behind Microsoft 365 authentication, VPNs, or IP allow-lists — even when shared between users in the same tenant. The one exception is native Microsoft services (SharePoint, OneDrive, etc.), which bypass the public unfurl bot entirely.
Common Reasons Teams Previews Fail
1. Missing Open Graph tags
Teams requires og:title at minimum. Without it, Teams may show only a raw URL with no preview card.
2. Page is not publicly accessible
Teams' unfurl bot cannot access pages behind authentication, VPNs, or other access controls — even within a Teams tenant. The URL must be reachable from the public internet.
3. 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. Switch to SSR, SSG, or pre-rendering.
4. 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, and anything behind a hotlink allowlist will fail.
5. Rate limiting or slow server responses
If your server is slow to respond or returns an error to the Teams bot, Teams may skip the preview silently and cache the failure.
6. Blocked bot user-agent
Aggressive WAFs and Cloudflare bot-fight settings can block Microsoft's crawler. Check your server logs for 403s or 429s from Microsoft user-agents.
7. CDN serving stale HTML
If you fixed your tags but Teams still shows the old URL unfurl, your CDN may still be serving the old HTML. Clear your CDN cache before re-pasting.
Open Graph Tags for Teams
Teams is an Open Graph consumer — the same tags that drive Facebook, LinkedIn, and Slack drive Teams. A complete Teams-ready Open Graph block looks like this:
<meta property="og:title" content="Your Page Title" />
<meta property="og:description" content="A concise description under 200 characters." />
<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" />
Recommended image spec for Teams:
| Requirement | Value |
|---|---|
| Minimum size | ~200 × 200 px |
| Recommended size | 1200 × 630 px |
| Aspect ratio | 1.91:1 |
| File type | JPG or PNG |
| URL type | Absolute HTTPS |
| Must be public | Yes — no auth, no hotlink protection, no IP allow-lists |
Step-by-Step Preview Troubleshooting
- Add Open Graph tags to your HTML
<head>(see the code block above). - Verify they're server-rendered — open a terminal and run:
curl -sL https://example.com/your-page | grep -iE '<meta (property|name)="(og|twitter)'
If the tags don't appear in the output, they're being set by JavaScript and Teams can't read them. Switch to SSR, SSG, or pre-rendering.
Confirm the image is accessible — open your
og:imageURL in a private browser window with no cookies. If it doesn't load there, Teams can't fetch it either.Test with TryUnfurl — paste your URL at TryUnfurl to see the detected Open Graph tags, image dimensions, and any issues — without needing to post in a real Teams channel.
Clear your CDN cache — if you fixed the tags but Teams still shows old data, your CDN (Cloudflare, Fastly, Azure Front Door) may still be serving the old HTML.
Re-paste the link in Teams — Teams does not expose a cache-clearing tool. Pasting the URL into a new chat or message triggers a fresh URL unfurl. If the preview was missing before and you've fixed the tags, the next paste should show the correct preview.
Common URL Unfurl Problems on Teams
- No preview card at all — missing
og:title, JS-rendered tags, or blocked bot user-agent. - Preview shows URL only, no image — missing
og:image, relative path, too small, or inaccessible to the Teams bot. - Old preview stuck — Teams cached an earlier URL unfurl. Re-paste the URL with a cache-buster query string (
?v=2) to treat it as a new URL. - Works for some users, not others — different Teams clients (desktop, web, mobile) can have different cache TTLs; check one at a time.
- Preview differs from what Open Graph looks like elsewhere — Teams may truncate
og:descriptionat 200 characters or drop a multi-line description. - Preview works from a personal Teams but not enterprise — your tenant may have link preview policies restricting unfurl for external URLs. Check with your Teams admin.
- Internal URLs don't unfurl — expected. Only public URLs unfurl unless you've built a custom Teams app with a messaging extension.
Testing Your Teams Link Previews
You don't need to spam a Teams channel to test a Teams URL unfurl. TryUnfurl fetches your page live, parses Open Graph and Twitter Card tags, and shows you the rendered preview alongside Facebook, LinkedIn, Slack, Discord, and iMessage — so you can confirm the Teams-ready Open Graph is in place before anyone sees the link.
For a migration, a campaign, or a monthly evergreen audit, the bulk URL unfurl checker runs up to 100 URLs in a single pass and exports the results as CSV.
Teams vs. Slack: Key Differences
| Feature | Microsoft Teams | Slack |
|---|---|---|
| Reads Open Graph tags | ✓ | ✓ |
| Reads Twitter Card tags | ✓ (fallback) | ✓ (fallback) |
| Executes JavaScript | ✗ | ✗ |
| Cache-clearing tool | None (re-paste / ?v=2) |
Delete + re-share / / command |
| Internal URL unfurling | Via custom Teams app connectors | Via Slack apps |
| Image minimum size | ~200 × 200 px | ~500 × 262 px for large card |
| URL unfurl for private URLs | Only for first-party MS services | No |
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 URL unfurl results for a period that varies by client. Re-pasting the URL into a new message usually triggers a fresh fetch; appending a query string (?v=2) forces Teams to treat it as a new URL.
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 URL unfurl bot.
How do I test my Teams URL unfurl without posting in a real channel?
Paste the URL into TryUnfurl — it renders the Teams-equivalent Open Graph preview card without requiring a Teams post. It also surfaces every detected Open Graph and Twitter Card tag.