How to Control WhatsApp Link Previews (and Fix When They Break)

Learn how WhatsApp link previews work, which OG tags WhatsApp reads, image size requirements, and how to fix a WhatsApp link preview that is not showing correctly.

Home/ Blog/ WhatsApp Link Preview

How WhatsApp Generates Link Previews

When you paste a URL into a WhatsApp chat, WhatsApp's servers send a crawler to fetch that URL. The crawler reads the Open Graph meta tags in the HTML head of your page, then assembles a preview card that appears below or alongside your message. This all happens on WhatsApp's servers, not on the recipient's device.

Here is a mock of what a working WhatsApp link preview looks like in chat:

Which OG tags WhatsApp reads

WhatsApp uses four Open Graph tags to build the preview card:

  • og:title — the bold title line in the preview card
  • og:description — the grey text below the title (usually 2 lines max)
  • og:image — the thumbnail image shown above or alongside the text
  • og:url — determines the domain name shown in the preview

WhatsApp does not read og:type, og:video, or Twitter Card tags. If those four tags are present and valid, WhatsApp has everything it needs to render a preview.

Correct OG tag structure
<head>
  <meta property="og:title" content="Your Page Title Here" />
  <meta property="og:description" content="A clear description under 200 characters." />
  <meta property="og:image" content="https://yoursite.com/images/preview.jpg" />
  <meta property="og:url" content="https://yoursite.com/this-page/" />
</head>

WhatsApp's crawler behavior

WhatsApp's crawler identifies itself with a user-agent string that includes "WhatsApp". The key behavioral traits you need to know:

  • No JavaScript execution — WhatsApp's crawler does not run JavaScript. If your OG tags are injected by a JavaScript framework after page load (common in React, Next.js with client-side rendering, or Vue SPAs), WhatsApp will not see them.
  • Server-side fetch — The fetch happens from WhatsApp's servers, not the user's device. IP-based geo-restrictions or bot-detection middleware can block it.
  • HTTPS required — WhatsApp will not follow HTTP image URLs for the preview thumbnail. All og:image values must be HTTPS.

Caching behavior (24-48 hours)

WhatsApp caches link preview metadata aggressively — typically for 24 to 48 hours. Once a link has been previewed in any chat, the cached version will continue to show even if you update your OG tags. Unlike Facebook, WhatsApp does not provide a cache-clearing tool.

The workaround: add a query parameter to force WhatsApp to treat the URL as a new resource. Sharing https://yoursite.com/page/?v=2 instead of https://yoursite.com/page/ will trigger a fresh metadata fetch. Use this when you update OG tags and need the new preview to appear immediately.

Quick tip: If you updated your OG tags and the old preview is still showing in a test chat, try sending the link with a ?v=2 parameter appended. WhatsApp will treat it as a new URL and fetch fresh metadata.

WhatsApp vs Other Platforms: OG Tag Support Comparison

Different messaging apps and social platforms handle Open Graph tags differently. Here is how WhatsApp compares to the other major platforms your links might be shared on:

Platform OG Tags Read Image Size JS Support Cache Duration
WhatsApp og:title, og:description, og:image, og:url 1200x630 recommended, max ~300KB No 24-48 hours
Telegram og:title, og:description, og:image, og:url, og:type 1280px max width, ~5MB limit No ~1 hour (with Telegram bot cache reset)
iMessage og:title, og:description, og:image, og:url 1200x630 recommended, no strict limit documented No Variable, clears after ~24h
Facebook Messenger og:title, og:description, og:image, og:url, og:video, og:type 1200x630, max 8MB Partial Clearable via Sharing Debugger

The practical takeaway: if you optimize your OG tags correctly for WhatsApp (static HTML, HTTPS image, correct dimensions), those same tags will work across all four platforms. WhatsApp is the strictest — satisfying WhatsApp means satisfying everyone else. See also our guide to Discord link embeds, which has its own quirks.

Why WhatsApp Link Previews Break: 5 Failure Patterns

Most broken previews come down to five repeating patterns. Here is each one with bad and good code examples.

1. Missing or empty og:image

Without an og:image tag, WhatsApp may render a text-only preview (title + description with no image) or no preview at all, depending on the client version.

Bad
HTML
<!-- No og:image tag at all -->
<meta property="og:title" content="My Product Page" />
<meta property="og:description" content="Buy our product here." />
Good
HTML
<meta property="og:title" content="My Product Page" />
<meta property="og:description" content="Buy our product here." />
<meta property="og:image" content="https://yoursite.com/img/product-preview.jpg" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

2. Image served over HTTP (not HTTPS)

WhatsApp will not load HTTP images for preview thumbnails. The image just goes blank even if the rest of the preview card renders correctly.

Bad
HTML
<meta property="og:image" content="http://yoursite.com/img/preview.jpg" />
<!--                              ^^^^ HTTP will be blocked -->
Good
HTML
<meta property="og:image" content="https://yoursite.com/img/preview.jpg" />
<!--                               ^^^^^ Always HTTPS -->

3. OG tags injected by JavaScript (client-side rendering)

If your site is a React, Vue, or Angular single-page app that renders OG meta tags client-side, WhatsApp's crawler will see an empty head — it does not execute JavaScript.

Bad
JavaScript (client-side)
// React component adding OG tags via react-helmet on mount
// WhatsApp crawler never sees these — it doesn't run JS
useEffect(() => {
  document.querySelector('meta[property="og:title"]')
    .setAttribute('content', 'My Page Title');
}, []);
Good
HTML (server-rendered or static)
<!-- OG tags must be in the static HTML response -->
<!-- Use Next.js getServerSideProps, SSG, or Nuxt SSR -->
<head>
  <meta property="og:title" content="My Page Title" />
</head>

4. Image file too large

WhatsApp has an undocumented but real file size limit for preview images. Images over roughly 300KB may load slowly or fail to display in the preview card — particularly on mobile connections.

Bad
Problem
<!-- Uncompressed PNG, 1.4MB -->
<meta property="og:image" content="https://yoursite.com/img/hero-raw.png" />
Good
Fixed
<!-- Compressed JPEG at 1200x630, 85KB -->
<meta property="og:image" content="https://yoursite.com/img/hero-og.jpg" />
<!-- Use tools like Squoosh, ImageOptim, or Sharp to compress -->

5. WhatsApp crawler blocked by server firewall or bot detection

If your hosting provider, CDN, or WAF blocks non-browser user agents, WhatsApp's crawler gets a 403 or timeout and no preview renders. Check that requests from WhatsApp's crawler user-agent are allowed through.

Bad
Server config (blocks all bots)
# .htaccess or nginx config blocking bot user-agents
# This catches WhatsApp's crawler too
if ($http_user_agent ~* "bot|crawl|spider|slurp") {
  return 403;
}
Good
Allowlist WhatsApp crawler
# Allow WhatsApp crawler through even with bot blocking in place
if ($http_user_agent ~* "WhatsApp") {
  # Allow through — do not apply bot-block rules
}
# Or more precisely: check for "WhatsApp/2" in the UA string

Image Requirements for WhatsApp Link Previews

Getting the image right is the single biggest lever for making WhatsApp previews look professional. Here are the specs that matter:

1200x630 Recommended dimensions (px)
1.91:1 Aspect ratio
300KB Recommended max file size
JPEG / PNG Supported formats

Dimensions

1200x630 pixels is the universal OG image standard and works correctly in WhatsApp. Images that deviate significantly from the 1.91:1 aspect ratio will be cropped — usually from the sides on landscape images or from the top and bottom on portrait images. Square images (1:1) render inconsistently depending on the WhatsApp client version and platform (iOS vs Android).

File size

Keep your OG image under 300KB. This is not an official WhatsApp limit (they have not published one), but images above this threshold frequently fail to load on mobile connections or in markets with slower average bandwidth. A well-compressed JPEG at 1200x630 should be between 60-120KB with no visible quality loss at preview size.

Supported formats

JPEG and PNG both work reliably. WebP support in WhatsApp previews is inconsistent across older client versions — do not use WebP for og:image if cross-compatibility matters. GIF files are not animated in WhatsApp link previews; they display as a static first frame.

Hosting requirements

  • Must be served over HTTPS (not HTTP)
  • Must be publicly accessible — no authentication required, no IP restrictions that would block WhatsApp's crawler
  • Must return a 200 status code (no redirects that end in a 404)
  • Avoid using query string tokens that expire — WhatsApp may re-fetch the image hours after the preview was first generated
Pro tip: Create a dedicated /og-images/ directory for your preview images with permanent, stable URLs. Changing the image URL invalidates the cached preview and forces a fresh fetch — useful when you want to update a stale preview.

How to Test Your WhatsApp Preview Before Sharing

There is no official WhatsApp preview testing tool (unlike Facebook's Sharing Debugger). The naive approach is to paste links into a test chat and check — but that is slow, does not show you why something is broken, and does not let you compare how the same link looks across WhatsApp, Telegram, iMessage, and Facebook Messenger simultaneously.

A faster approach is to use Share Preview — a multi-platform OG tag tester built specifically for this workflow.

What Share Preview shows you

  • A rendered preview of how your link will look on WhatsApp, Telegram, Discord, Facebook, and iMessage — side by side
  • Which OG tags were found and what values they returned
  • Whether your og:image is accessible, what its dimensions are, and whether the file size is within safe limits
  • Whether your page is server-rendering OG tags or injecting them client-side (the most common invisible problem)
  • The raw meta tag output that WhatsApp's crawler would see

How to use it

  1. 1
    Go to share-preview.com and paste your URL into the test input.
  2. 2
    Select WhatsApp from the platform dropdown (or view all platforms at once).
  3. 3
    Read the tag audit — Share Preview tells you which tags are missing, if the image is HTTPS, and what the crawler actually sees in your page source.
  4. 4
    Fix the issues, re-deploy, and re-test with ?v=2 appended to bypass caching.

Test Your WhatsApp Link Preview Now

Paste your URL and see exactly how WhatsApp, Telegram, iMessage, and Discord will render it — before anyone else does.

Open Share Preview →

For deeper reading on OG tags generally, see our complete OG image guide and our link preview overview covering all major platforms.

Frequently Asked Questions

Why is my WhatsApp link preview not showing?
The most common causes are: a missing or malformed og:image tag, an image served over HTTP instead of HTTPS, a file size over ~300KB, OG tags injected by JavaScript rather than present in the static HTML, or WhatsApp's crawler being blocked by a server firewall or WAF rule. Paste your URL into Share Preview to see exactly which tags WhatsApp's crawler would find and whether the image is accessible.
How do I change my WhatsApp link preview image?
Update the og:image meta tag in your page's HTML <head> to the new image URL. The image should be 1200x630px, under 300KB, in JPEG or PNG format, and served over HTTPS. After deploying the change, share the URL with a ?v=2 parameter appended to bypass WhatsApp's 24-48 hour cache and force a fresh preview fetch.
How long does WhatsApp cache link previews?
Approximately 24 to 48 hours. WhatsApp does not provide a cache-clearing tool, so you cannot force an immediate refresh for a specific URL. The workaround is to share the link with a unique query parameter (e.g., ?v=2) so WhatsApp treats it as a new URL and fetches fresh metadata. Existing previews in sent messages cannot be updated retroactively.
WhatsApp preview vs Facebook preview: what is the difference?
Both use Open Graph tags, but Facebook reads more of them (including og:video and og:type), partially executes JavaScript, supports larger image files (up to 8MB), and offers the Sharing Debugger tool for instant cache clearing. WhatsApp is stricter: no JavaScript execution, HTTPS-only images, a recommended 300KB file size limit, and no official cache-clearing mechanism. The OG tags themselves are the same standard — the differences are enforcement. Passing WhatsApp's requirements means your link will preview correctly on Facebook too.

Check Your WhatsApp Preview Right Now

Share Preview renders your link exactly as WhatsApp, Telegram, Discord, and iMessage would see it — before you share anything publicly.

Test at Share Preview →