Make a Next.js Open Graph image show up on WhatsApp

The first time I tried sharing my Next.js app on WhatsApp, the preview looked… wrong. Sometimes there was no image at all, sometimes it showed an old image I had already replaced, and sometimes it worked on other apps but refused to work on WhatsApp.

After a bit of digging, I realized the “Open Graph image works” bar is higher when WhatsApp is involved. It’s not enough to set og:image and call it a day — WhatsApp is picky about the image URL, picky about the file itself, and it also caches previews aggressively.

Here’s the setup that worked consistently for me.

WhatsApp wants an Open Graph image it can fetch easily and quickly. In practice, that means the image must be publicly accessible without cookies or authentication, and the og:image value should be an absolute URL, not a relative path. So instead of something like:

/opengraph-image.jpeg

you want:

https://www.demo-nextjs-project.com/opengraph-image.jpeg

That absolute URL detail matters more than you’d think, because some scrapers don’t reliably resolve relative paths the way browsers do.

The next thing WhatsApp cares about is the shape and weight of your image. A really safe target is 1200×630 px, and keeping the file under 300KB is a good rule of thumb if you want fewer surprises. JPEG is usually the simplest “just works” choice for link previews, especially if the image is more photo-like or has gradients.

Once the image is hosted at a stable URL, the remaining job is making sure your page is outputting the right Open Graph metadata server-side. If you’re using the App Router, Next.js gives you a clean way to do this via the metadata export. The important part is that your Open Graph image resolves to a fully qualified URL, which is where metadataBase helps a lot.

A simple working example looks like this:

export const metadata: Metadata = {
  metadataBase: new URL("https://demo-app.vercel.app"),
  title: "Demo App ",
  description: "Demo app for demonstrating opengraph image",
  openGraph: {
    type: "website",
    url: "https://demo-app.vercel.app/",
    siteName: "Demo App",
    images: [
      {
        url: "https://demo-app.vercel.app/opengraph-image.jpeg",
        width: 1200,
        height: 630,
        alt: "demo-app-opengraph-image",
        type: "image/jpeg",
      },
    ],
  },
  twitter: {
    card: "summary_large_image",
    title: "Demo App",
    description: "Demo app for demonstrating opengraph image",
    images: ["https://demo-app.vercel.app/opengraph-image.jpeg"],
  },
};

At this point, sharing your link should show the preview, but there’s a very common gotcha: caching.

WhatsApp (and other platforms in the same ecosystem) may cache the preview information for a while. So you update the meta tags or replace the image and… WhatsApp keeps showing the old preview. That can make you think your configuration is broken even when it’s correct.

This is where the Facebook Link Debugger is usefull.

Even if you’re not building “for Facebook”, the debugger is a practical way to force a re-scrape of your page. When you paste your page URL into the Facebook Link Debugger and click to debug, it fetches your page again, reads the Open Graph tags, and refreshes what it thinks the preview should be. In many cases, this refresh also helps WhatsApp pick up the new image/metadata faster, because they share a similar scraping/caching ecosystem.

So whenever you change your Open Graph image, title, or description and you don’t see the update on WhatsApp, do this:

Open Facebook Sharing Debugger, paste your page URL, and trigger a new scrape (“Scrape Again”). After that, try sending the link on WhatsApp again — it often switches from “stale preview” to “correct preview” in a few minutes.

One more thing: make sure your OG image URL is reachable without redirects or blockers. If you have bot protection, auth middleware, geo restrictions, or anything that might treat scrapers differently than browsers, it can prevent the preview from being generated. A quick sanity check is opening the Open Graph image URL in an incognito tab and confirming it loads instantly:

https://www.demo-nextjs-project.com/opengraph-image.jpeg

If that loads reliably and your page source contains the correct og:image value (again, absolute), you’re in a good place.

In short: host a lightweight 1200×630 image, ensure og:image resolves to an absolute URL, and when WhatsApp refuses to update, use the Facebook Link Debugger to force a re-scrape. That combination is what finally made my previews stable and predictable.