Troubleshooting guide

iMessage link preview not showing?

Messages on iPhone, iPad and Mac builds a link preview from your page’s Open Graph tags. Without them the link shows as a gray bubble with the page title, domain and a small icon. Here’s what to check, based on Apple’s own guidelines.

The check opens on the iMessage preview and flags a missing og:title, a missing og:image and small images.

What iMessage needs

Tags: og:title and og:image, plus og:site_name for the site name
Image: At least 900 px wide. Under 150 px is shown as an icon
Icon: apple-touch-icon or favicon, square, at least 108 px
Limits: Page HTML up to 1 MB, images and videos up to 10 MB together

From Apple’s TN3156 ↗

Common causes and fixes

1
There’s no og:image

Without an image, Messages falls back to a gray bubble with the page title, your domain and a small icon. That’s the most common reason a link looks plain.

Fix: Add og:image with a full https:// address. Check your page to see which tags it has, then copy the generated code into your <head>.
2
The image is too small

Apple asks for images at least 900 px wide. Images under 150 px may be ignored or shown as an icon instead of a large picture.

Fix: Use a 1200×630 image. The OG image generator makes one in your browser.
3
The tags are added by JavaScript or behind a meta refresh

Messages doesn’t run JavaScript and doesn’t follow <meta http-equiv="refresh"> redirects. It reads the HTML at the address that was shared. Server-side redirects are followed.

Fix: Put the tags in the HTML your server sends, and replace meta refresh redirects with server redirects (301 or 302).
4
The page or the image is too large

Messages stops at 1 MB for the page itself and 10 MB for the icon, image and video together. Pages with huge inline scripts or data, and uncompressed images or videos, can go over.

Fix: Keep the meta tags near the top of the <head>, and save the image as a JPG well under 1 MB.
5
Bot protection blocks the preview

Firewalls, bot protection and login walls can stop Messages from reading the page. Developers report that it identifies itself as facebookexternalhit/1.1 Facebot Twitterbot/1.0.

Fix: Let that user agent through your bot protection, and open the page and image in a private window to confirm they’re public.
6
The page is behind a login

If the shared address redirects to a sign-in page, every link shows “Sign In” as its title. Apple suggests giving protected pages their own meaningful tags, without revealing anything private.

Fix: Serve og:title and og:image for the page itself, even to visitors who aren’t signed in.

Still seeing the old preview?

Apple doesn’t document how long Messages keeps a preview, and a sent message keeps the preview it had. To test a fix, send the link again with a query string such as ?v=2.

Send this instead

example.com/page?v=2

Next fix, next number: ?v=3

Questions

What people ask when the fixes above don’t explain it.

Why does it say Tap to Load Preview?

Messages doesn’t load previews automatically for links from senders who aren’t in your contacts. Tapping loads it. Nothing on your page causes this, and saving the sender as a contact stops it.

Why doesn’t the description show?

Messages shows the title, image and domain, not og:description. It only uses the description for posts on social networks. Put what matters in og:title and the image.

Why does my site name appear twice?

Messages already shows your domain, so a title like “Pricing | Acme” repeats it. Apple recommends a short, specific og:title without branding, and the site name in og:site_name.

Should the image have text in it?

Apple advises against it. Messages shows the image at different sizes on different devices, so text can become unreadable. Keep the image graphical and the words in the title.

Can the preview play a video?

Yes. Point og:video at a downloadable video file, such as an MP4, and Messages plays it inline. A link to a video page that needs an embed won’t play.