Skip to content

A glossary story9 chapters · 6 min read

Link Preview

The title, description and image WhatsApp shows for the first URL in a text message when the send sets the preview_url flag.

Also called: preview_url · URL preview · Rich link preview · Open Graph preview

Reviewed

Follow along

Keep your link in one piece

A URL can only carry a small set of characters; everything else travels as %XX bytes.

Try

Try spaces, &, ?, # or ₹.

Encoded, safe after utm_campaign=
order%20updates
Characters in
13
Characters out
15
  • 1 character became %XX escapes; letters, digits and - _ . ! ~ * ' ( ) pass through unchanged.
  • Spaces became %20. HTML forms use + for a space instead — never mix the two styles.
WhatsApp previews the first URL it finds, and a raw space ends that URL, & starts a new parameter and # starts a fragment. Pick a campaign value to see it percent-encoded so the whole link survives.

Chapter 1 · The scenario

Example: Order-tracking links for a Pune bakery

A Pune bakery that takes cake orders on WhatsApp sends each customer an order-tracking link. At first the preview shows nothing but a plain link: the site's bot protection answered WhatsApp's crawler with a challenge page, and the og:image was a 2.4 MB PNG. The team lets the WhatsApp/ user agent through on the tracking pages, server-renders an og:title such as "Order #4471: Red velvet, 1 kg" and swaps in an 85 KB 1200 × 630 JPEG. The next messages show a full card with the cake photo above the link.

— Order-tracking links for a Pune bakery

Chapter 2 · What is a link preview?

A link preview is the small card WhatsApp shows with a link in a chat: the page's title in bold, a short description and a thumbnail image. On the WhatsApp Cloud API you ask for one by sending a Text Message with preview_url set to true in the text object. WhatsApp then tries to fetch the first URL in the body and render a preview; without the flag, or when the page cannot be fetched or read, the customer simply sees a tappable link.

The card is built from the linked page, not from your API request. WhatsApp requests the URL with an HTTP GET whose User-Agent begins WhatsApp/ and reads Open Graph tags inside the <head>: og:title, shown bold on up to two lines; og:description, one or two lines in smaller text, for which about 80 characters is enough; og:url, the canonical URL without session or tracking parameters; and og:image, an absolute URL for the thumbnail. Meta's guidance is that the <head> must appear within the first 300 KB of the HTML and that the image should be under 600 KB, at least 300 pixels wide and no wider than 4:1. Pages that miss these rules may get a small preview or none.

Only the first URL in the body is previewed, and it must begin with http:// or https://. A link preview is also not the same as an Interactive CTA URL Message: that hides the address behind one labelled button and shows no preview card, while a preview keeps the raw URL in the text and adds the card. For business-initiated messages outside the customer service window, links go in templates, either in the body or behind a call-to-action (CTA) button such as a Dynamic URL Button.

Key takeaways

  • A link preview is the card (title, description, thumbnail) WhatsApp draws for the first URL in a text message when preview_url is true.
  • WhatsApp builds it from the page's Open Graph tags: og:title, og:description, og:url and og:image.
  • Meta's rules: the <head> within the first 300 KB of HTML, and an image under 600 KB, at least 300 px wide.
  • Only the first URL is previewed, it must start with http:// or https://, and a preview is best-effort, never guaranteed.
  • Unlike a CTA URL button, a preview keeps the raw link in the text and decorates it with a card.

Chapter 3 · How it unfolds

How does a link preview work?

  1. Add Open Graph tags to the page

    Put non-empty og:title, og:description and og:url tags, plus og:image, in the server-rendered <head>, within the first 300 KB of the HTML.

  2. Prepare the preview image

    Use an absolute HTTPS URL to a JPEG or PNG under 600 KB, at least 300 px wide, no wider than 4:1. A 1200 × 630 image is a common safe choice.

  3. Let WhatsApp's crawler in

    The fetch is a plain GET with a WhatsApp/2.x user agent and an Accept-Language header. Make sure bot protection, login walls and geo-blocks return the real page to it, quickly and with status 200.

  4. Send with preview_url

    Set text.preview_url to true and put the link you want previewed first in the body, with http:// or https:// and every query value percent-encoded.

  5. Test before a campaign

    Meta's own check: paste the link into a WhatsApp chat without sending and wait about 10 seconds for the preview. No preview means a tag or access problem; a small preview usually means the image misses the rules.

Chapter 4 · Why it matters

Why does a link preview matter?

A bare link in a chat can look like spam; a link with a recognisable title and image looks like your brand and tells the customer what they are about to open. For marketers a working preview supports trust and clicks on order pages, invoices, articles and booking links. For developers it is a case where the bug usually lives on the website, not in the WhatsApp request: a firewall challenging the crawler, an oversized image, or tags injected by JavaScript.

Chapter 5 · Where it goes wrong

Common mistakes with a link preview

  • Blocking the crawler

    Bot protection, CAPTCHAs, geo-blocking and login walls answer WhatsApp's request with a page that has no tags. Allow the WhatsApp/ user agent through on pages you share.

  • Tags added by JavaScript

    WhatsApp reads the HTML the server returns. Open Graph tags inserted by a client-side framework after load are not there when the crawler looks, so render them on the server.

  • Heavy or relative preview images

    An og:image over 600 KB, narrower than 300 px or given as a relative path produces a small preview or none. Serve an absolute URL to a light, correctly shaped image.

  • The wrong link comes first

    Only the first URL is previewed, and www.example.in without a scheme does not count as one. Put the link you care about first and write it in full with https://.

  • Unencoded characters in the URL

    A raw space ends the link, & starts a new parameter and # starts a fragment, so the preview and the tap go to the wrong address. Percent-encode query values, as the scene shows.

Chapter 6 · In code

A link preview in code

curl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/messages" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "919812345678",
    "type": "text",
    "text": {
      "preview_url": true,
      "body": "https://shop.example.in/track/4471?utm_source=whatsapp&utm_campaign=order%20updates\nYour red velvet cake is out for delivery."
    }
  }'

The first URL in the body gets the preview; any later URLs stay plain links.

Chapter 7 · The facts

A link preview: key facts and limits

Flagtext.preview_url = true
Which linkFirst URL in the body, http:// or https:// only
Tags readog:title, og:description, og:url, og:image
HTML budget<head> within the first 300 KB
ImageUnder 600 KB, ≥ 300 px wide, aspect ratio ≤ 4:1
CrawlerHTTP GET, User-Agent WhatsApp/2.x… (A, I or N)
GuaranteeBest effort; otherwise a plain link

Chapter 8 · What good teams do

Best practices for a link preview

  • Keep og:title free of branding and short enough for two lines.
  • Use UTM Parameters on the shared link for analytics, but keep og:url clean and canonical.
  • Serve the same tags to WhatsApp as to everyone else; vary only the language, using Accept-Language, if you need to.
  • Re-test previews after any site redesign or CDN change, before the next campaign goes out.
  • Apply WhatsApp Text Formatting to the sentence around the link, not to the URL itself.

Chapter 9 · Link Preview FAQs

Link Preview FAQs

Why is my WhatsApp link preview not showing?+
Usually the page, not the message. Check that `preview_url` is true, the link is the first URL and starts with https://, the page returns its Open Graph tags to a `WhatsApp/` user agent without a challenge or login, and the image is under 600 KB.
What image size does WhatsApp need for a link preview?+
Under 600 KB, at least 300 pixels wide, with an aspect ratio no wider than 4:1, referenced by an absolute URL in `og:image`. A 1200 × 630 JPEG of around 100 KB meets every rule.
Can WhatsApp preview more than one link in a message?+
No. Only the first URL in the body gets a preview; later URLs are shown as plain tappable links. Send separate messages if two links each need a card.
Should I use a link preview or a CTA URL button?+
Use a preview when seeing the page's title and image builds trust, and a CTA URL button when the address is long or ugly and a clear label matters more. A CTA URL message shows no preview card.
Does a link preview change what a message costs?+
No. Meta charges per delivered message by category, and a preview is just how the text is displayed. A text reply inside an open window is a service message, charged at ₹0.145 in India since 1 October 2026.

See InfiQ pricing

* Per-message rates for India, ex-GST: marketing, utility and authentication effective 1 July 2026; service messages ₹0.145 since 1 October 2026 (they were ₹0 until 30 September 2026). Volume commitments earn discounts — final rate is confirmed on your account; applicable GST extra. Rates for other countries differ (see the international rate table on /pricing).

From definition to your first message

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms