How to Make a Web Page Link Preview Appear in iMessage
Add Open Graph metadata and a site icon so iMessage can show a useful link preview. Learn the HTML, image requirements, and fixes for common issues.
To make a web page link preview appear in iMessage, add Open Graph metadata such as og:title and og:image to the page’s HTML source, and provide a site icon. The metadata must be available in the page response: Messages does not run JavaScript to create the preview. Use an absolute URL for the preview image, then share the page’s ordinary HTTPS URL in Messages.
1. Add metadata to the page source
Put the metadata in the document’s <head>. Replace the example title, description, and image URL with values for the specific page. The image URL must be absolute and publicly fetchable.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Trail Guide: Eagle Ridge Loop</title>
<meta property="og:title" content="Eagle Ridge Loop Trail Guide">
<meta property="og:description" content="Route details, distance, and trail conditions for the Eagle Ridge Loop.">
<meta property="og:image" content="https://example.com/images/eagle-ridge-guide.jpg">
<meta property="og:url" content="https://example.com/guides/eagle-ridge-loop">
<meta property="og:type" content="website">
<meta property="og:site_name" content="Example Outdoors">
<link rel="apple-touch-icon" sizes="180x180" href="https://example.com/icons/apple-touch-icon.png">
<link rel="icon" href="https://example.com/favicon.ico">
</head>
<body>
<h1>Eagle Ridge Loop Trail Guide</h1>
</body>
</html>og:title and og:image are the essential examples Apple documents. The other Open Graph fields provide useful context and help identify the page. Keep the title concise and specific to the page; put the site’s brand in og:site_name rather than repeating it in every title.
Make the image work at preview size
- Use artwork relevant to the linked page, not a generic site banner.
- Apple recommends an image at least 900 pixels wide. Images narrower than 150 pixels may be ignored or shown as icons.
- Avoid text in the image: preview cards can appear at different sizes, making small text hard to read.
- Keep the image file reasonably sized and accessible without a login or special browser state.
Provide an icon too
A page-specific image does not make the site icon unnecessary. Messages may use an Apple touch icon, favicon, or another declared icon, including as a fallback if the image is unavailable. Apple recommends a square icon at least 108 by 108 pixels. The example declares both a touch icon and a favicon; use URLs that return actual image files.
2. Make the metadata available without JavaScript
View the page’s raw HTML response and confirm the Open Graph tags are already present in the <head>. A client-rendered app may show the right title in a browser after JavaScript runs while still serving an empty or generic document to the process that creates the Messages preview.
Apple’s guidance is explicit: “JavaScript does not run when creating rich links,” so Open Graph tags need to be in the page source rather than generated dynamically. If your framework renders pages on the server or during static generation, emit the tags there. For authenticated pages, return useful generic metadata without exposing private content.
Messages follows server-side redirects, but does not follow meta refresh redirects. Put metadata on the final page URL and use a normal HTTP redirect when redirecting. Share the final canonical URL where possible.
3. Check Apple’s asset limits
Apple’s published guidance in TN3156: Creating a Rich Link specifies these figures:
| Resource | Apple guidance |
|---|---|
| Site icon | Square, at least 108 × 108 pixels |
| Preview image | At least 900 pixels wide |
| Very small image | Below 150 pixels wide, it may be ignored or displayed as an icon |
| Main page resource | Maximum 1 MB |
| Associated icons, images, and videos combined | Maximum 10 MB |
These are Apple’s published recommendations and limits, not a guarantee that every device will render the same card. Optimize the image and icon, and keep the total associated resources within the stated limit.
4. Test the link in Messages
- Deploy the page and assets to their public HTTPS URLs.
- Check the raw HTML response for the metadata, and open the image and icon URLs directly to verify they load.
- Send the page URL in a Messages conversation and allow time for the preview to be generated.
- Review the result on the devices and page types that matter to you. Image selection and layout can vary.
Apple’s reviewed guidance does not document a guaranteed way to force-refresh an existing preview. After changing metadata, test by sharing the URL again, but do not assume a particular cache-clearing action will force an immediate update.
5. Optional: use a directly linked video
Apple describes inline playback for a directly linked, downloadable, playable media asset referenced through og:video or twitter:player:stream. HLS streams require a tap to start, and videos that depend on an HTML-embedded player do not play inline. For a video preview, choose a playable media file and keep the associated assets within Apple’s combined resource limit. See Apple’s rich-link presentation for its explanation of media behavior.
Or skip the browser setup
If what you need is a screenshot of the page for documentation, review, or an automated workflow, ScreenshotNeo is a website screenshot API and MCP server. It does not create an iMessage link preview; it returns a page screenshot or PDF from one request. For this example, call the API with your page URL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com/guides/eagle-ridge-loop -o shot.webpSee the ScreenshotNeo API documentation for request options. Python and Node.js callers can use the same endpoint and URL parameter:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={
"access_key": "YOUR_API_KEY",
"url": "https://example.com/guides/eagle-ridge-loop",
},
timeout=90,
)
r.raise_for_status()
with open("shot.webp", "wb") as f:
f.write(r.content)const q = new URLSearchParams({
access_key: 'YOUR_API_KEY',
url: 'https://example.com/guides/eagle-ridge-loop',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', new Uint8Array(await res.arrayBuffer()));ScreenshotNeo removes cookie 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 per month are free with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.
Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| No rich preview appears | Metadata is missing from the source HTML, or the page cannot be fetched publicly. | Inspect the initial HTML response, confirm the tags are in <head>, and make sure the URL loads without authentication. |
| Preview has the wrong title or image | The tags describe another page, the image URL is invalid, or the preview has not refreshed. | Check the exact URL’s source and open the absolute image URL directly. Share the updated URL again; no guaranteed force-refresh method is documented. |
| The image is missing or appears as an icon | The image may be too small, unavailable, or unsuitable as an associated resource. | Use a publicly accessible image at least 900 pixels wide and keep it above 150 pixels wide; verify the response serves the image itself. |
| The browser shows metadata but Messages does not | The browser may execute JavaScript that inserts tags after initial load. | Render metadata server-side or statically so it exists before JavaScript runs. |
| A redirecting page has no expected preview | A meta refresh redirect is used, which Messages does not follow for rich-link creation. | Use a server-side redirect and place the metadata on the destination page. |
| Video does not play inline | The URL points to an HLS stream or an HTML player embed. | Use a directly linked downloadable, playable media asset; HLS requires a tap, and HTML-dependent embeds do not play inline. |
FAQ
Can I change the preview for a link someone already sent?
Change the metadata served by the page, then share the URL again to check the result. Apple’s cited guidance does not promise a way to refresh a preview already created.
Does this change what every messaging app displays?
No. Open Graph tags are commonly used for link previews, but the details here describe Apple Messages behavior; other clients can interpret page metadata differently.
Does ScreenshotNeo generate an iMessage preview?
No. ScreenshotNeo captures a web page as an image or PDF. To influence an iMessage preview, add metadata and an icon to the linked page as described above.
