You paste a link into a Microsoft Teams chat, hit send — and the card that comes back shows a title and a description but a big gray rectangle where the image should be. Or worse: the thumbnail is your old logo from two rebrands ago. Teams is where B2B teams, support channels, and product announcements actually get shared — over 300 million daily active users — yet link previews in Teams fail in ways that Facebook and Twitter never do, mostly because Teams has no public debugger and Microsoft's crawler is one of the strictest in the business.
Teams builds previews with Microsoft's link unfurl service: when you paste a URL, Microsoft fetches the page, reads the Open Graph meta tags, and renders a card with a title, a description, and a thumbnail. If the og:image tag is missing, unreachable, or too small, Teams silently falls back to a text-only card — or worse, to a favicon. There's no "Scrape Again" button and no Card Validator, and in corporate tenants an admin can switch link unfurling off entirely, which makes troubleshooting feel like guessing.
In this guide, I'll cover why Teams previews lose their images, the exact specs Microsoft's crawler expects, and the step-by-step fix I use — verified with ogimgen's free OG checker.
Why Your Teams Link Preview Shows No Image
Microsoft's unfurl service behaves like any other social crawler: fetch the page once, read the meta tags, cache the result against the URL. When the image is missing from the card, the cause is almost always one of these:
- No og:image tag at all. Teams renders the card from whatever it finds — title and description only, or the site's favicon as a placeholder.
- An image that's too small. Like most platforms, Microsoft's crawler rejects tiny images. Below roughly 200×200 pixels, the thumbnail is dropped and the card renders without an image.
- An image URL the crawler can't reach. HTTP URLs, redirect-heavy links, hotlink protection, and signed or expiring URLs all make the fetcher give up silently.
- An oversized, slow image. A 5 MB PNG can exceed the crawler's patience, and the preview times out with no thumbnail.
- The crawler is blocked at the edge. robots.txt rules, Cloudflare bot protection, or WAF rules that block Microsoft's user agent prevent the fetch entirely.
- A stale cached preview. Microsoft caches previews against the URL. Update the image and the old one can stick around for days.
- Link unfurling is disabled by IT. In Microsoft 365 tenants, admins can turn off link previews for the whole organization. If every link you paste shows a bare URL, that's an admin setting, not your site.
The two that matter most for most sites: a missing or too-small og:image, and a crawler that's being blocked at the edge.
The OG Image Specs Teams Actually Needs
Teams reads the same standard Open Graph tags as every other platform — og:title, og:description, and og:image — and falls back to <title> and <meta name="description"> when they're missing. If your OG setup already works on Slack or WhatsApp, it will almost certainly work on Teams:
| Setting | Teams Requirement | Why It Matters |
|---|---|---|
| Minimum size | 200×200 px | Below this, the image is rejected entirely |
| Recommended size | 1200×630 px | Crisp in both chat cards and expanded previews |
| Display crop | Thumbnail, center-weighted | Keep key text in the center of the canvas |
| File size | Under 1 MB | Heavy images delay or fail the preview |
| Format | PNG or JPG | Both work; PNG for text-heavy cards |
| HTTPS | Required | HTTP images are silently dropped |
| Crawler access | Microsoft's fetcher allowed | Blocked crawler = no preview data at all |
The required meta tag set looks exactly like this — the same six tags that work on Facebook, LinkedIn, and WhatsApp:
<meta property="og:title" content="Your Page Title">
<meta property="og:description" content="A short, punchy description">
<meta property="og:image" content="https://yoursite.com/og-image.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:url" content="https://yoursite.com/page">One Teams-specific detail: unlike Slack or Discord, Teams keeps the thumbnail small in regular chat messages, while the first link in a message can expand into a larger preview. A 1200×630 image with your headline centered will survive both crops cleanly.
How to Fix a Missing or Stale Teams Preview (Step by Step)
Teams has no public debugger like Facebook's Sharing Debugger or Twitter's Card Validator, so you have to verify and bust the cache yourself. This is the sequence I use — it catches the vast majority of Teams preview problems:
- Verify your tags first. Paste your URL into our free OG image checker. It shows exactly what a crawler sees — title, description, image, and dimensions. If the checker reports a missing or broken og:image, Teams will never render a thumbnail.
- Fix the underlying issue. Add or correct the OG tags on your page, regenerate a proper 1200×630 image if yours is below 200×200, and confirm the checker shows a valid card. Double-check that the image URL is public, HTTPS, and not behind a redirect.
- Check robots.txt and CDN rules. Make sure Microsoft's crawler isn't blocked. If you use bot-management services (Cloudflare Bot Fight Mode, DataDome, etc.), whitelist Microsoft's fetcher or the fetch gets challenged.
- Bust the cache with a query parameter. Microsoft caches previews against the URL. Appending
?v=2(or any unique string) to the og:image URL makes the crawler treat it as a brand-new image. Update the tag, save, and re-verify with the checker. - Delete the message and re-paste the link. In the Teams chat, delete the message containing the link and paste it again. This forces a fresh unfurl against the current URL instead of the cached one.
- Check with your IT admin. If every link in your tenant shows a bare URL with no card at all, link unfurling is probably disabled at the organization level — nothing on your site can fix that, and it's worth ruling out before you chase your own tags.
Teams vs. Slack vs. Discord: Preview Behavior Compared
Teams, Slack, and Discord are the three work-chat platforms where your links get shared most often. They all read the same OG tags, but the card treatment and the failure modes differ:
| Aspect | Teams | Slack | Discord |
|---|---|---|---|
| Card style | Compact card, small thumbnail | Medium card with thumbnail | Large 1.91:1 card |
| Public debugger | None | None | None |
| Cache refresh | New URL, delete and re-paste | Query param | Query param |
| Recommended image | 1200×630 | 1200×630 | 1200×630 |
| Admin control | IT can disable unfurling org-wide | Workspace admins can toggle previews | No per-server toggle |
The practical takeaway: because all three platforms consume the same six OG tags, one well-built 1200×630 image covers Teams, Slack, and Discord at the same time — which is exactly the setup I recommend in the Slack link preview guide too.
Summary
Teams link previews lose their images for five main reasons: missing or too-small og:image tags, an image URL Microsoft's crawler can't reach, an oversized file that times out, edge rules that block the fetcher, and aggressive caching. The fix is the same sequence every time — generate a 1200×630 image with your headline centered, set the standard OG tags, unblock Microsoft's crawler, append a query parameter to bust the cache, and delete-and-re-paste the link in the chat.
Teams previews are how your product looks inside the tool millions of teams use to make decisions every day, and a branded card beats a gray rectangle every time. Generate your OG image with ogimgen in about 30 seconds, verify the tags with the OG checker, re-paste the link — and check what it looks like in Slack as well, since the same tags drive both.