How to Set a Link Preview Image for Microsoft Teams
Set the image Teams shows when someone shares your page by adding Open Graph metadata. Learn how schema.org and app-based link unfurling differ.
To change the image Microsoft Teams shows for a link to a website you own, add an Open Graph og:image tag to that page’s HTML <head>. Add og:title and og:description too: Microsoft recommends supplying all three for the best preview. The image URL should be publicly reachable so the preview service can retrieve it. Microsoft’s Share to Teams documentation describes these metadata fields.
1. Add Open Graph metadata to the page
Put the tags in the <head> of the exact page URL people will share. Replace the example values with page-specific content and an absolute HTTPS URL to your image.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Product guide</title>
<meta property="og:title" content="Product guide">
<meta property="og:description" content="A practical guide to the product.">
<meta property="og:image" content="https://example.com/images/product-guide.jpg">
</head>
<body>
<h1>Product guide</h1>
</body>
</html>The code above is a minimal example. Add the tags to your existing document rather than replacing the rest of its head. Make sure each shared page has the metadata for that page, rather than reusing one image and description across unrelated URLs.
What each tag controls
| Tag | Purpose | What to check |
|---|---|---|
og:image |
The preview thumbnail | Its content is the full URL of the image you want displayed. |
og:title |
The preview title | Use a clear title that matches the page. |
og:description |
The preview description | Summarize the page accurately. |
Microsoft’s cited guidance does not specify one universal image dimension or guarantee identical rendering across Teams clients. Use an image appropriate to the page and verify how the preview appears in the clients your audience uses; do not treat a particular pixel size as a Teams requirement based on this guidance.
2. Check that Teams can get the image
- Open the exact page URL you plan to share and inspect its HTML source. Confirm the three Open Graph tags are present in the head and have the intended values.
- Open the
og:imageURL directly in a browser. It should resolve to the intended image without requiring a login or a browser session. - Paste the page URL into a Teams chat or channel and inspect the resulting preview. If you recently changed metadata, test with care: the cited 30-minute cache behavior in Microsoft’s documentation applies to app-based link unfurling, not necessarily to ordinary website metadata previews.
For a quick visual check of what a page returns, you can capture the page with ScreenshotNeo, a website screenshot API and MCP server. A screenshot can help spot a page that renders blank or is covered by an overlay, but it does not replace checking the actual metadata in the page source.
3. Choose the right implementation route
| Route | Use it when | What it involves |
|---|---|---|
| Open Graph metadata | You own the website and want to set the normal link preview. | Add page-level image, title, and description tags. This is the simplest route for a site thumbnail change. |
| Schema.org JSON-LD | You want to provide structured website data for Teams-supported templates. | Add the supported schema properties in JSON-LD. Microsoft documents this as a way to provide rich previews without installing a Teams app. |
| App-based link unfurling | You publish a Teams app and control the registered domain. | Declare domains in the app manifest and implement a service that responds to Teams link queries with a card. |
4. Use schema.org JSON-LD for a supported rich preview
Microsoft also documents website micro-capabilities based on schema.org. This route uses an application/ld+json script and supported schema properties and templates; it can provide rich previews without a Teams app. Follow Microsoft’s micro-capabilities and schema documentation for the supported types and properties. Do not assume arbitrary JSON-LD fields will become preview fields: use the documented properties for the template you need.
5. Build a custom card with app-based link unfurling
If you control a Teams app and want a custom card for links on its registered domains, implement link unfurling. The app manifest declares the domains under composeExtensions and messageHandlers. When a matching link is pasted, Teams sends a link query to the app service, and the service returns a card that can include an image. This requires the app manifest and service work; it is not a setting a regular Teams user can apply to any third-party URL. See Microsoft’s link-unfurling guide.
Microsoft documents a 30-minute cache for app link-unfurling results. That caching detail applies to this app-based route; it should not be generalized to ordinary website metadata previews. The same documentation says this feature supports Adaptive Cards version 1.3 and earlier, and mobile support is limited to links that do not require authentication.
Or skip the browser setup
If you need to inspect how a page renders before debugging its preview, ScreenshotNeo can return a screenshot with one GET request. It is separate from changing Teams metadata: add the Open Graph tags above to control the link card.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| The expected thumbnail does not appear. | The page’s og:image is missing, points to the wrong asset, or was added to a different page. |
Inspect the shared URL’s HTML head and correct its page-specific metadata. |
| The image URL opens for you but not for the preview. | The image may depend on your logged-in session or otherwise be inaccessible to the preview fetcher. | Use a publicly reachable image URL and check it in a private browser session. |
| The title or description is wrong or absent. | og:title or og:description is missing or has stale values. |
Set both fields alongside og:image, then share the exact page URL again. |
| A Teams app card does not update immediately. | App-based unfurling results are cached for 30 minutes according to Microsoft’s documentation. | Allow for that app-specific cache behavior when checking a change. Do not assume that cache duration applies to ordinary metadata previews. |
| An app unfurl does not work on mobile. | The link may require authentication; Microsoft documents limited mobile support for links that do not require authentication. | Check the authentication requirements and mobile limitation in the app unfurling documentation. |
Performance, reliability, and maintenance
- Keep metadata in the rendered page head. Verify the source returned for the shared URL contains the intended tags; a value configured in a page builder is not useful if it does not appear in the delivered HTML.
- Use stable, reachable image URLs. If you replace an image, update the metadata to the right asset and verify that URL directly.
- Set all three fields. Microsoft recommends the image, title, and description together for the best result.
- Choose the route that matches ownership. Website metadata and JSON-LD are suitable site-level routes; a custom app card requires a Teams app and service.
- Account for documented app behavior. For app unfurling, plan around its documented 30-minute result cache and card version and mobile constraints.
Frequently asked questions
Can I change the preview image for a website I do not own?
The website owner controls its page metadata. An app-based card can be handled by an app for domains it has registered, but it is not a general user override for any link.
Do I need to install a Teams app to get a rich website preview?
No. Microsoft documents schema.org JSON-LD micro-capabilities for rich previews without installing a Teams app.
Does the app-unfurling cache mean every Teams link preview is cached for 30 minutes?
No. The cited 30-minute behavior is documented for app-based link unfurling and does not establish the cache behavior for ordinary website metadata previews.
Can ScreenshotNeo set the Teams thumbnail for me?
No. ScreenshotNeo captures a website image; your site’s Open Graph metadata or a Teams app’s returned card determines the link preview image.
