ToolsWhisper.io
All tools

Open Graph Tags: Why Your Link Preview Looks Wrong and How to Fix It

3 min readFrank
seosocial-media

Paste a link into a chat, a social post or a message thread, and the app fetches the page and builds a card from it: a title, a description and usually an image. That card is the first impression for every shared link, and it is controlled by a few lines in the page's <head>.

When it goes wrong, it goes wrong in a handful of predictable ways. This post covers what the tags are, what each platform reads, and the reasons a corrected preview still looks broken.

The tags that matter

The Open Graph protocol, published at ogp.me, defines four required properties for a page: og:title, og:type, og:image and og:url. In practice, these are the ones worth setting on every page:

<meta property="og:title" content="Page title">
<meta property="og:description" content="One or two sentences.">
<meta property="og:url" content="https://example.com/page">
<meta property="og:type" content="website">
<meta property="og:site_name" content="Example">
<meta property="og:image" content="https://example.com/cards/page.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="What the image shows">

Use og:type of article for posts and add article:published_time if you have a date. Everything else is optional.

X (formerly Twitter) reads its own twitter:* tags and falls back to the Open Graph ones when they are missing. The one worth setting explicitly is twitter:card. Use summary_large_image to get the wide image layout.

The Open Graph tag generator writes the full set for you and shows a preview of the card as you edit, which is the quickest way to see a bad image or a truncated title before publishing.

The image does most of the work

A card with a strong image gets noticed; a card with none, or a cropped logo, gets scrolled past. The conventional size is 1200 × 630 pixels, a 1.91:1 ratio, and it holds up across platforms. Some details that cause trouble:

  • Absolute HTTPS URLs only. A relative path such as /cards/page.png means nothing to a crawler that is not on your site.
  • Keep the important part central. Some surfaces crop to a square or a different ratio. Text near the edges gets cut off.
  • Do not put the whole message in the image. Titles and descriptions are read as text. An image-only message is invisible to anything that cannot see it, and the og:image:alt text is what assistive technology reads.
  • Keep the file small. Heavy images can fail to load in a preview. Messaging apps are the usual offenders, and WhatsApp in particular is commonly reported to drop images much above roughly 300 KB. ToolsWhisper's own homepage card was 487 KB as exported from the design tool. Reducing the colour palette brought it to 40 KB with no visible difference. A flat-colour card with text compresses very well. The image compressor does this kind of reduction in the browser, and the notes in how to compress images without uploading them explain the trade-offs.

Why the fix does not show up

The most common support question is some version of "I changed the tags and the preview is still wrong." There are four usual reasons.

The platform cached the old version. Platforms fetch your page once and remember what they found. Changing your tags does not notify them. Meta's Sharing Debugger and LinkedIn's Post Inspector both let you fetch the page again and refresh the stored preview. Messaging apps may hold their own cache that you cannot clear, and the only fix there is time or a new URL.

The tags are not in the HTML the crawler receives. Most link-preview crawlers do not run JavaScript. If your site is a single-page app that adds the meta tags after load, the crawler sees an empty head. The tags must be in the HTML as served. This site generates them at build time, which is why view-source shows them.

The image is blocked or redirected. If your robots.txt blocks the folder that holds the image, crawlers that respect it will not fetch the card, and a redirect chain on the image URL can also break it. The robots.txt guide covers how that goes wrong.

There are two sets of tags. A theme or plugin emits one set, someone adds a second, and the crawler uses whichever comes first. View the page source and search for og:image. There should be exactly one.

A checklist before you publish

  1. One og:title, one og:description, one og:image, in the served HTML.
  2. The image is at least 1200 × 630, under a few hundred KB, with an absolute HTTPS URL.
  3. og:url matches the canonical URL of the page.
  4. twitter:card is set to summary_large_image.
  5. You have run the URL through a debugger, so the platform's cache holds the version you intended.

The title and description in these tags can differ from the ones search engines show. If you are writing both, the meta tag generator previews the search result as well, and why Google rewrites your meta description explains when your text will not be used.