WhatsApp and iMessage link previews: how they are built and how to fix them

Where does a WhatsApp link preview come from?

From the sender's side. WhatsApp's developer page on link previews says that when you compose a message containing a link, "on behalf of the sender, WhatsApp will crawl this URL and attempt to generate a link preview." The request is a plain HTTP GET, and the preview appears above the composer box before you press send. Previews work for links sent in a chat and links shared to Status.

The WhatsApp Help Center backs this up from the privacy side. Its article on disabling link previews explains that turning the setting on means the links you send will not generate a preview, and presents this as a way to protect your IP address. In other words, the device composing the message is the one that contacts your server.

The crawler identifies itself. WhatsApp documents a User-Agent of the form WhatsApp/2.x.x.x A, I or N, for Android, iOS and web, with examples such as WhatsApp/2.22.20.72 A. The request also carries an Accept-Language header set to the recipient's chosen language, if any, so a multilingual site can answer in that language.

Which tags does WhatsApp read?

WhatsApp's page lists four pieces of mark-up for the page head: a title, a description, a canonical URL and an image. On a WordPress site these come from the same Open Graph set every other network reads, so if your SEO plugin already prints og:title, og:description, og:url and og:image, there is nothing extra to add. Our guide to setting up Open Graph in WordPress covers the one-source rule. The specific requirements WhatsApp sets are these.

WhatsApp says it makes a best attempt when these rules are not met, relaxing requirements, looking for other mark-up and falling back to a small preview, but warns that this "should not be relied on."

How do iMessage link previews work?

Apple's technical note TN3156, Create rich previews for Messages, first published in 2017 as TN2444 and republished in April 2024, describes the Messages app on iOS and macOS. Without Open Graph data, Messages shows a gray bubble with the page title, the domain and a small icon. With og:title and og:image it shows an image and a caption. Apple's note does not say whether the sender's or the recipient's device fetches the page, so we do not claim either.

• Title. Keep og:title short and specific, and leave the site name out of it. Apple asks you to put the site name in og:site_name instead, because branding in the title duplicates other parts of the preview.
• Image. og:image supplies the picture. Apple advises against text in the image, since it may be shown at varying sizes and become unreadable; put words in the tags.
• Icon. Messages also uses an icon: an apple-touch-icon, a favicon, or an icon named in a link rel element. If you lack an image of sufficient size or quality, Apple suggests relying on the apple-touch-icon.
• Video. An og:video or twitter:player:stream pointing at a downloadable file such as MPEG-4 downloads and plays automatically. Streams such as HLS need a tap. Video that needs embedding HTML will not play inline.
• Same tags for everyone. Serve identical metadata to mobile and desktop user agents.

What image size works in both apps?

Each app documents a different floor, and only Apple names a target. These are the numbers from the two official pages, nothing more.

A 1200 by 630 JPEG, the size explained in our Open Graph image size guide, clears Apple's 900 pixel width and WhatsApp's 300 pixel width and sits well inside the 4:1 ratio. The figure to watch is WhatsApp's 600KB cap: a full quality export of a photo at that size can exceed it, so compress it. Apple notes its numbers are guidelines that may change.

Test a WhatsApp or iMessage preview by messaging yourself

Neither app offers a debugger like Facebook's. The test is a real message. Before you start, paste your page's HTML into our paste-the-source preview checker to confirm the tags are there; it runs in your browser and fetches nothing, so it shows what you serve, not what a crawler cached.

1. 01

   Check the WhatsApp setting

   On Android tap the three dots menu, then Settings, Privacy, Advanced, and make sure Disable link previews is off. It is off by default. If it is on, the links you send will never show a preview.

2. 02

   Compose, do not send

   Open a chat with yourself or a test contact and paste the full URL. WhatsApp's own instructions say to wait: if no preview appears above the composer within 10 seconds, recheck the tag and image requirements.

3. 03

   Send and look at the size

   Tap send. If the preview arrives small rather than large, WhatsApp points you back to the image rules: width, aspect ratio and the 600KB limit.

4. 04

   Test in Messages

   In the Messages app on iPhone or Mac, start a new message addressed to your own number or Apple Account, paste the URL and send it. Look for the image and title rather than the plain gray bubble.

Why is a preview missing or stale?

Most failures come from one of the documented rules.

• Tags past the 300KB mark. Large inline scripts or styles placed before the meta tags push the head beyond WhatsApp's window. Move the Open Graph tags near the top of the head.
• An image over 600KB. The commonest cause of a small WhatsApp card. Compress the file, or point og:image at a smaller crop.
• A relative image URL. WhatsApp asks for an absolute URL. /wp-content/uploads/... without the scheme and host does not qualify.
• Tags written by JavaScript. Apple states that Messages previews do not run JavaScript or follow meta refresh redirects. Server-side redirects are followed. Tags injected by a script after load are invisible.
• A login wall. Apple asks that pages behind sign in still carry meaningful metadata for the page itself, so the preview does not read "Sign In" for every link.
• The crawler is blocked. A firewall rule that challenges unknown clients can answer WhatsApp's GET with a challenge page. Allow user agents beginning WhatsApp/.
• Different tags per device. Apple asks for the same metadata for every user agent. A mobile theme that drops the image breaks previews only on phones.
• The sender disabled previews. With Disable link previews on, nothing is fetched. Ask the person who sent the plain link.

Stale previews are a different problem. Because WhatsApp builds the preview while the sender composes, a message sent yesterday keeps yesterday's card; editing your tags changes only messages composed after the edit. Neither WhatsApp nor Apple documents a cache you can clear or a refresh tool. If a brand new message still shows old text, the stale copy is usually on your side: purge your page cache and CDN for that URL, confirm the new tags in a private window, then compose again. The same purge first habit fixes old images on Facebook shares, and the tool-by-tool picture is on the link previews and Open Graph hub.

Sending links from the WhatsApp Business API

If your site sends WhatsApp messages through the Cloud API, previews are opt in. The text message reference lists a preview_url field: set it to true and the WhatsApp client will attempt to render a preview of a URL in the body. The body text can be up to 4096 characters. The preview still depends on the same page tags.

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "New guide: https://example.com/town-clock/"
  }
}

That example mirrors the request in Meta's reference, with an invented link. Compare how other apps treat the same tags in Slack's unfurl rules, and see what platforms remove from shared images if you rely on embedded image metadata.

What goes wrong

• Branding in the title. Both WhatsApp and Apple ask for a title without the site name. "Town clock repair | Example Journal" wastes one of WhatsApp's two bold lines.
• A long description. WhatsApp shows one or two lines and says 80 characters will suffice. Anything past that is cut.
• Tracking parameters in og:url. WhatsApp wants the canonical URL with no session or user parameters. Keep UTM tags out of og:url.
• Text baked into the image. Apple warns it may become unreadable at small sizes.
• Expecting old messages to update. They will not. Only new messages pick up the change.

Check it worked

• View source, logged out: one og:title, og:description, og:url and og:image, near the top of the head.
• The og:image URL is absolute, opens in a private window, is at least 900 pixels wide, and is under 600KB.
• A WhatsApp message composed to yourself shows a preview above the composer within 10 seconds, and arrives as a large card after sending.
• A message to yourself in Apple Messages shows the image and title rather than the gray bubble.
• The title carries no site name, and og:site_name holds it instead.

Sources

• Meta for Developers, WhatsApp Business Platform: Link Previews (updated May 21, 2026)
• WhatsApp Help Center, How to disable link previews
• Meta for Developers, WhatsApp Cloud API: Text messages
• Apple Developer, TN3156: Create rich previews for Messages (first published 2017 as TN2444, republished April 30, 2024)

Questions

Related reading

1. 01Open Graph image size: 1200 by 630 and the safe zoneThe right Open Graph image size is 1200 by 630 pixels at a 1.91:1 ratio. Minimums, file limits, formats, and a centre safe zone for square crops.6 min read
2. 02Adding Open Graph tags in WordPressAdd Open Graph tags to WordPress with an SEO plugin or theme code: the four required tags, image tags, per-post overrides, and how to avoid duplicate tags.7 min read
3. 03Link preview checker: test your Open Graph and card tagsPaste a page's HTML to check its Open Graph and X card tags, see mock previews, and find duplicate, missing or relative tags. Runs in your browser only.10 min read
4. 04Slack link preview: how unfurling works and how to fix itHow Slack builds a link preview: the tags its robot reads, its user agent, the 30 minute cache, how to test, remove or block a preview, and why one fails.10 min read
5. 05What platforms strip from shared images: EXIF, XMP and C2PAWhat platforms strip from shared images: how EXIF, XMP and IPTC fields and C2PA manifests die on upload or preview fetch, plus a probe method and a table.7 min read