Open Graph for WhatsApp
How to configure Open Graph meta tags for WhatsApp link previews, image requirements (300KB limit), caching quirks, and troubleshooting.
WhatsApp is one of the most popular instant messaging applications globally. When users share links in WhatsApp chats, the app generates a visual preview box containing a thumbnail image, page title, and domain name.
However, WhatsApp link previews have strict technical constraints — particularly regarding image file size — that often cause previews to fail.
Required Open Graph Tags for WhatsApp
WhatsApp’s crawler reads standard Open Graph tags from the HTML <head>:
<meta property="og:title" content="Page Title for WhatsApp Preview" />
<meta property="og:description" content="A brief summary shown in chat windows." />
<meta property="og:image" content="https://example.com/images/whatsapp-thumb.png" />
<meta property="og:url" content="https://example.com/page-url" />WhatsApp Image Requirements: The 300 KB Rule
The single most common reason WhatsApp previews fail is image file size.
| Property | Requirement |
|---|---|
| Maximum File Size | 300 KB (Strict limit) |
| Recommended Dimensions | 1200 × 630 pixels (or 800 × 800 px) |
| Aspect Ratio | 1.91:1 or 1:1 |
| Supported Formats | JPEG, PNG |
⚠️ CRITICAL: If your
og:imagefile size exceeds 300 KB, WhatsApp will silently fail to download the thumbnail, displaying only text.
How to Fix Oversized WhatsApp Thumbnails
- Compress your preview image using WebP/JPEG compression or tools like TinyPNG.
- If your primary
og:imageis high-res (e.g., 2 MB), specify a smaller secondary image using standard image tags or dynamic compression parameters.
WhatsApp Caching Quirks
WhatsApp caches link previews on a per-chat / per-client basis. Unlike Facebook or LinkedIn, WhatsApp does not provide a public web debugger tool for clearing cache.
How to Force WhatsApp to Fetch Fresh Previews
If you update your page’s OG tags and need to verify the new preview in WhatsApp:
- Add a cache-busting query parameter to the URL when pasting into chat:
https://example.com/my-page?v=2 - Wait 2–3 seconds in the WhatsApp text input box before pressing send — WhatsApp generates the preview during typing!
Why WhatsApp Previews Fail
- Image over 300 KB: Compressed images under 300 KB are mandatory.
- Missing HTTPS: Image URLs must use secure
https://. - Pasting Too Fast: If you paste a link and hit “Send” immediately, WhatsApp will send plain text before the preview bot finishes scraping.
- Server Timeout: WhatsApp’s bot has a strict 3-second request timeout. If your server is slow, the preview will fail.