How to Create WhatsApp Link Preview Images from Webpages with APITemplate.io
Generate a page-specific image with APITemplate.io, add it as your page’s og:image, and check the metadata when a WhatsApp preview is missing or stale.
To create a WhatsApp link preview image with APITemplate.io, make an image template, create a Direct URL for it, and put that generated URL in the webpage’s og:image metadata. Use different template values for different pages when each page needs its own image. This sets up the webpage metadata; the sources available for this guide do not establish WhatsApp’s current image requirements, metadata precedence, or preview cache behavior, so verify the result in the WhatsApp context you care about.
How the workflow fits together
There are three parts: generate an image, associate it with a page through Open Graph metadata, and check what the published page exposes. APITemplate.io documents both a Direct URL workflow and a backend API workflow. The Direct URL is the shortest route when the values can safely be assembled into a URL. The POST API is useful when a backend or integration already supplies the page-specific values.
- Create a reusable image template in APITemplate.io.
- Generate an image URL for the template, supplying any dynamic element values.
- Set that URL as the page’s
og:imagevalue. - Publish the page and inspect its metadata and image URL independently.
- Check the shared link in the WhatsApp client and context that matters to your users.
Build a reusable APITemplate.io image template
- Open Manage Templates and create an image template. Choose a preset or custom dimensions, then open the editor.
- Add the elements the image needs, such as a headline, background image, and decorative shapes. Name dynamic elements clearly; you will use those names in the URL or API overrides.
- Use the editor preview to check the composition with representative values. Keep important content away from edges and make sure the image still works with short and long titles.
- Open the editor’s Direct URL tab, create an auth code, set the available quota and expiration options, and save the settings.
The Direct URL pattern documented by APITemplate.io is https://rest.apitemplate.io/v2/create-image-url/{template_id}?auth={auth_code}&{element.property}={value}. A text element named headline can be populated with headline.text; an image element can use a property such as background.src. Encode query parameter values rather than concatenating raw page content into the URL.
Generate a page-specific image with a Direct URL
For example, replace the placeholders with the template ID, auth code, and values that match your template. The example uses a headline and background image; include only properties supported by the elements in your own template.
https://rest.apitemplate.io/v2/create-image-url/YOUR_TEMPLATE_ID?auth=YOUR_AUTH_CODE&headline.text=Product%20release&background.src=https%3A%2F%2Fexample.com%2Fassets%2Frelease.jpgWhen generating this URL in application code, use a URL builder so spaces, ampersands, question marks, and non-ASCII characters are escaped correctly.
const endpoint = new URL('https://rest.apitemplate.io/v2/create-image-url/YOUR_TEMPLATE_ID');
endpoint.searchParams.set('auth', 'YOUR_AUTH_CODE');
endpoint.searchParams.set('headline.text', 'Product release');
endpoint.searchParams.set('background.src', 'https://example.com/assets/release.jpg');
console.log(endpoint.toString());Create a distinct set of values for each page that needs a distinct preview image. APITemplate.io documents using query parameter changes to produce page-specific images. Make sure the generated image URL you place in the metadata is the complete URL, including its query string.
Add the generated image to the webpage metadata
Put the generated image URL in the page’s Open Graph image metadata. Render the value in the HTML head of the actual page, not only in client-side code that may run after a crawler fetches the document.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta property="og:title" content="Product release">
<meta property="og:description" content="Read about the product release.">
<meta property="og:image" content="GENERATED_IMAGE_URL">
</head>
<body>
<h1>Product release</h1>
</body>
</html>Replace GENERATED_IMAGE_URL with the complete Direct URL. For a server-rendered site, build the value from the page’s data and escape it for an HTML attribute. For a static site, ensure each page contains its own intended value. Do not put an APITemplate.io API key in public page source; the documented Direct URL method uses its auth code, while the POST workflow uses an API key on the server side.
Alternative: generate the image with the APITemplate.io POST API
Use the POST route when a backend should submit the dynamic values rather than exposing them as page URL parameters. APITemplate.io documents the v2 create-image endpoint, a template ID, an X-API-KEY header, and JSON overrides keyed by template element and property. The exact endpoint hostname can vary by the documented region; choose the endpoint for your deployment from the current APITemplate.io documentation.
Example request shape using cURL:
curl -X POST "https://YOUR_REGION_ENDPOINT/v2/create-image" \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_API_KEY" \
-d '{
"template_id": "YOUR_TEMPLATE_ID",
"overrides": {
"headline": { "text": "Product release" },
"background": { "src": "https://example.com/assets/release.jpg" }
}
}'Keep the API key in a server-side secret store and make the request from a backend or trusted integration. The editor’s API Console can help create sample JSON and preview generated output. Confirm the response format and output retrieval steps against the current API documentation for the endpoint and region you use.
Check the page and diagnose missing or stale previews
- Inspect the published HTML. Find the
og:imagetag in the page head and confirm it contains the intended full image URL, including encoded query values. - Open the image URL directly. Confirm it returns the generated image rather than an error or an HTML page. Check that dynamic text and image inputs actually appear in the output.
- Check page-specific output. Compare two pages that should have different images. Verify their metadata values differ and that each generated URL uses the intended values.
- Test in the target WhatsApp context. The available research does not establish WhatsApp’s current preview parsing or cache refresh behavior. Avoid treating a stale preview as proof that image generation failed; check the current WhatsApp or Meta guidance for cache-related behavior.
| Symptom | Likely cause | What to check or change |
|---|---|---|
| No image appears on the page preview | The published page may have a missing, incorrect, or late-rendered og:image. |
Inspect the actual HTML returned for the page and verify the metadata URL. |
| The generated image URL fails | The template ID, auth code, quota, expiration, or query parameters may be wrong. | Check the Direct URL settings and open the URL independently. Rebuild it with proper URL encoding. |
| Text or background is missing | A parameter may not match the name or property of a template element. | Check element names and properties in the template, then compare the URL parameters or API overrides. |
| Every page shows the same image | The pages may share the same metadata URL or dynamic values. | Render page-specific values and inspect each page’s published og:image. |
| WhatsApp still shows an older image | The shared context may be showing previously fetched preview data. | First confirm the current page metadata and image output. Then consult current WhatsApp or Meta guidance on preview refresh; the available sources do not establish a cache-clearing procedure. |
| POST request is rejected | The key, endpoint region, request shape, or override names may not match the current API configuration. | Check the current v2 API endpoint and required headers, validate the JSON, and compare overrides with the template element names. |
Choosing Direct URL or POST
| Consideration | Direct URL | POST API |
|---|---|---|
| How values are supplied | Template properties are query parameters. | Template properties are JSON overrides. |
| Where to assemble values | Where the page’s metadata URL is generated. | In a backend or integration that can make an authenticated request. |
| Authentication described in the workflow | Auth code in the Direct URL, with configurable quota and expiration. | API key in the X-API-KEY request header. |
| Useful inspection route | Open the generated URL and inspect the image. | Use the editor’s API Console to prepare sample JSON and preview output. |
The available source material does not support ranking these routes by cost, speed, or WhatsApp success rate. Choose based on where your page data lives and whether you already have a secure backend integration.
Reliability, performance, and cost considerations
- Keep generation inputs deterministic. Use stable page data and properly encoded URL values so the same page consistently points to its intended image.
- Validate before publishing. Preview representative short and long titles, inspect the generated image URL, and check the live page’s metadata after deployment.
- Protect credentials. Keep POST API keys on the server. Set Direct URL auth settings deliberately, including quota and expiration, and review their access implications in the vendor’s current documentation.
- Plan for preview variance. A correct Open Graph tag does not, based on the sources available here, establish how quickly a particular WhatsApp client will fetch or refresh an image.
- Do not assume unsupported limits. The research does not establish WhatsApp image dimensions, file limits, format support, or cache duration. Verify current platform requirements before standardizing an image pipeline.
Or skip the browser setup
If you also need to inspect how a page renders before choosing or validating its preview image, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request captures a page as PNG, JPEG, WebP, or PDF. It removes known consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000.
cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://example.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);See the ScreenshotNeo API documentation for request options. Sign up for 1,000 free screenshots a month with no card.
FAQ
Does adding og:image guarantee WhatsApp will show the image?
No guarantee is established by the available sources. The metadata workflow is documented by APITemplate.io, but WhatsApp’s current parsing rules and client behavior should be checked against current platform guidance.
Can every page have a different image?
Yes. APITemplate.io documents using different query parameter values for page-specific generated images. Make sure the page outputs the corresponding unique URL in its metadata.
Should I use Direct URL or the POST API?
Use Direct URL when query parameters fit your page-generation setup. Use POST when a backend should send authenticated JSON overrides.
Where can I find WhatsApp’s current image limits?
The research material for this article does not establish them. Check current WhatsApp or Meta documentation before relying on particular dimensions, formats, or file-size limits.
