WhatsApp Rich Link Previews & Open Graph Guide

WhatsApp supports interactive Rich Link Previews when sending URLs via chat or campaign broadcasts. A properly optimized link preview replaces plain blue text with a high-converting card featuring a large image thumbnail, bold headline, and summary text.

1. How WhatsApp Link Previews Work

When a link is included in a WhatsApp message, WhatsApp's crawler performs an HTTP GET request to fetch the Open Graph (og:) metadata embedded in the webpage's <head>.

2. Meta's Technical Requirements

To ensure WhatsApp renders a full-size, rich preview card, your landing page must meet the following technical rules:

Specification	Rule	Why It Matters
Head Tag Location	Must appear within the first 300 KB of the HTML response.	WhatsApp aborts scanning if `<head>` or `og:` tags are buried behind heavy scripts or bloated DOMs.
`og:title`	Bold headline, max 2 lines without excessive brand clutter.	The primary text shown to the recipient in WhatsApp's message card.
`og:description`	Secondary text, 80 characters max (1–2 lines).	Clean, punchy subtitle explaining the offer or action.
`og:url`	Clean canonical URL.	Free of session IDs, temporary tracking tokens, or dynamic hashes.
`og:image` Size	Maximum 600 KB file size.	Images larger than 600 KB are dropped, falling back to text only.
`og:image` Dimensions	Minimum 300 px width, aspect ratio 4:1 or less (1.91:1 standard recommended).	Ensures crisp display on high-DPI mobile screens without awkward cropping.
Protocol	Absolute HTTPS URL with valid SSL certificates.	Insecure HTTP image links are blocked by WhatsApp security filters.

3. Crawler Identification & Handling

WhatsApp crawls landing pages using a dedicated crawler with specific HTTP headers:

User-Agent: WhatsApp/2.x.x.x A|I|N
- A = Android
- I = iOS
- N = Web / Desktop
Accept-Language: Sent according to the user's phone language setting (e.g. en, hi, ar).

[!TIP]
Ensure your web server or Cloudflare/firewall configuration does not block user-agents containing WhatsApp/. If bot protection blocks the request or serves a CAPTCHA challenge, WhatsApp cannot generate the preview.

4. Enabling Link Previews in SMSPort

When sending outbound messages via SMSPort API or Cloud API, link previews are controlled via the preview_url flag in text message payloads:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919876543210",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "Your appointment is confirmed! View details here: https://cityhospital.com/appointment"
  }
}

Set "preview_url": true to instruct Meta Cloud API to crawl the URL and attach the rich preview card.
When set to false, only plain text with a clickable blue URL will be dispatched.

5. Testing & Verification Checklist

Composer Test: Type or paste your URL in WhatsApp. Wait up to 10 seconds.
Card Verification: Confirm the full-size banner image appears above the text input before pressing send.
Fallback Check: If only a tiny thumbnail or no image appears, verify that your image is strictly under 600 KB and the Open Graph tags are within the first 300 KB of the page's HTML.