Set a Link Preview Image for Microsoft Teams

When you paste a link into a Microsoft Teams chat or channel, Teams automatically generates a preview card with a title, description, and an image. By default, Teams pulls that image from the page’s Open Graph meta tags. If you want to control which image appears—or fix a missing or wrong one—you need to edit those tags on your website. This guide walks you through the process, from understanding how Teams selects the image to testing and troubleshooting your setup.

What You’ll Need

Access to the HTML source code of the webpage you want to share (via a CMS, a code editor, or a web developer).
An image file hosted at a public URL (HTTPS recommended). It should be at least 300×200 pixels, but larger (like 1200×630) is better for high-resolution displays.
Optional: A way to preview your page’s meta tags (browser developer tools, a social sharing debugger, or a simple text editor).

Step-by-Step

Create or choose your image. Use a PNG, JPG, or GIF (animated GIFs usually show the first frame). Make sure it’s publicly accessible—Teams’ crawler must be able to fetch it without login. A common size is 1200×630 pixels (the Open Graph recommended ratio), but any image at least 300×200 will work.

Add Open Graph meta tags to your page’s <head> section. The essential tags are:

<meta property="og:title" content="Your Page Title">
<meta property="og:description" content="A short description of your page.">
<meta property="og:image" content="https://example.com/images/your-image.jpg">
<meta property="og:url" content="https://example.com/your-page">

The og:image tag is the one that controls the preview image. You can also add og:image:width and og:image:height to help crawlers, but they’re optional.

Ensure the image URL is absolute. Use the full URL starting with https://, not a relative path like /images/pic.jpg. Teams’ crawler needs a direct, publicly reachable URL.
Publish the changes. Save the file and deploy it to your live site. If you’re using a CMS, clear any caching layers (like CDN or server cache) so the updated meta tags are visible to the crawler.
Test the link in Teams. Paste the URL into a Teams chat or channel. If the image doesn’t appear immediately, try the next steps.
Force a refresh of Teams’ cache. Teams caches link previews. To force a refresh, you can append a query string to the URL (e.g., ?v=2) and paste that. Or, use the Bing Webmaster Tools URL submission, or simply wait a few hours.
If the image still doesn’t show, check for conflicting tags. Some pages have multiple image tags (e.g., og:image and twitter:image). Teams primarily uses og:image, but if it’s missing, it may fall back to the first <img> on the page. Make sure your og:image is correct and that the URL is not blocked by robots.txt.

Common Mistakes

Using a relative URL for the image—Teams can’t resolve it.
Image too small. Teams may ignore images smaller than 300×200 pixels, especially if they’re tiny thumbnails.
Image not publicly accessible. If the image is behind a login, a firewall, or a hotlink protection service, Teams can’t fetch it.
Forgetting to update the og:title and og:description. Even if you only care about the image, Teams uses the whole card. A missing or generic title can make the preview look unprofessional.
Editing the wrong page. If you’re testing a staging URL, make sure you’re actually editing the live version that Teams sees.

Tips

Use a dedicated image that is relevant to the content—not just a logo. A clear, high-contrast image will make your link stand out in a busy feed.
Keep the image under 5MB to ensure fast loading. Teams may time out if the image is too large.
Test with a private message first. Send the link to yourself in a chat before posting it to a public channel.
If you use a CMS like WordPress, there are plugins (like Yoast SEO) that let you set the social share image without editing code directly.
Use a URL shortener with preview control? No—that won’t help. The preview is based on the final destination page, not the shortener.

Troubleshooting

No image appears at all. Check if your page has any og:image tag. If not, Teams will try to grab the first image on the page. If that fails, you’ll see a card with only text. Add the tag and test again.

Old image still shows. Teams caches previews aggressively. Try appending a query string (like ?v=2) to the URL to bypass the cache. If that works, the issue is caching. You can also try using a different URL format (e.g., with or without trailing slash).

Image is wrong (shows a different one). This usually happens when the og:image tag is missing or malformed. Open your page’s source in a browser (right-click → View Page Source) and search for og:image. Make sure the content attribute is exactly the URL you want.

Teams shows a generic icon or a broken image. The image URL might be returning a 404 error. Open the URL directly in a browser to verify it loads. Also check that the image file format is supported (PNG, JPG, GIF, WebP—avoid BMP or TIFF).

Changes don’t reflect after hours. Try using the Bing Markup Validator or the Facebook Sharing Debugger to see what meta tags are being read. These tools often show you exactly what the crawler sees and can help pinpoint issues.

Frequently Asked Questions

Does Teams use Twitter Card tags instead of Open Graph?

No, Teams primarily uses Open Graph (og:) tags. Twitter Card tags (twitter:) are ignored. Make sure your og:image is set correctly.

Can I set a different image for Teams than for Facebook or Twitter?

Yes, you can use conditional tags or a CMS that lets you specify different images per platform. However, Teams only reads Open Graph, so you’d need to serve different og:image tags based on the user agent. This is advanced—most sites just use one universal image.

Why does Teams show a screenshot instead of my image?

If Teams can’t find an og:image or the image fails to load, it may fall back to taking a screenshot of the page. To avoid this, ensure your og:image is valid and accessible.

How long does it take for Teams to update the preview after I change the image?

It can take anywhere from a few minutes to several hours. Teams caches previews, so if you need it immediately, append a query string to the URL to force a fresh fetch.

Do I need to add the `og:image:width` and `og:image:height` tags?

No, they’re optional. Teams doesn’t require them, but including them can help the crawler process the image faster and avoid layout shifts.

Can I use an SVG file as the preview image?

It’s not recommended. Teams and most crawlers expect raster formats like PNG or JPG. SVG files often fail to render in preview cards.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →