Social Previews

When a WarpLink URL is shared on social media (Twitter, Facebook, Slack, iMessage, etc.), it displays a rich preview card with a title, description, and image. This is automatic. No extra configuration needed.

How It Works

WarpLink detects social media bots by matching the User-Agent against a list of known crawler patterns:

1. Bot detected: WarpLink returns a full HTML page with Open Graph and Twitter Card meta tags
2. Real user: WarpLink returns a 302 redirect to the destination

This split approach ensures:

• Social platforms get the metadata they need for rich previews
• Real users get instant redirects without seeing an interstitial page

Bot Detection

WarpLink checks the User-Agent against a maintained list of known crawler patterns. Common patterns include:

• Twitterbot: Twitter/X card crawler
• facebookexternalhit: Facebook Open Graph crawler
• LinkedInBot: LinkedIn preview crawler
• Slackbot: Slack unfurl crawler
• WhatsApp: WhatsApp preview crawler
• Googlebot: Google search crawler

When a bot is detected, WarpLink serves HTML instead of a redirect.

Meta Tags

The HTML response includes both Open Graph and Twitter Card tags:

<meta property="og:title" content="Check out this product" />
<meta property="og:description" content="Amazing deal on..." />
<meta property="og:image" content="https://example.com/image.jpg" />
<meta property="og:url" content="https://aplnk.to/abc123" />
<meta property="og:type" content="website" />

<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="Check out this product" />
<meta name="twitter:description" content="Amazing deal on..." />
<meta name="twitter:image" content="https://example.com/image.jpg" />

Configuring Previews

Set social preview metadata when creating or updating a link:

curl -X POST https://api.warplink.app/v1/links \
  -H "Authorization: Bearer wl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_url": "https://example.com/product",
    "og_title": "Check out this product",
    "og_description": "Amazing deal you won'\''t want to miss",
    "og_image_url": "https://example.com/product-image.jpg"
  }'

If no OG metadata is set on the link, WarpLink redirects the crawler straight to the destination URL, so its own Open Graph tags render instead.

Best Practices

• Image size: Use images at least 1200x630px for optimal display across platforms
• Title length: Keep titles under 60 characters to avoid truncation
• Description length: Keep descriptions under 155 characters
• Image format: JPEG or PNG. Avoid SVG (not supported by most crawlers)
• HTTPS images: All image URLs must use HTTPS

How Bot Detection Actually Works

The pattern list that decides "is this a bot" lives in a key-value store, not in the code that checks it, which is why the list can be updated without redeploying anything. Detection is a case-insensitive substring match: WarpLink lowercases the incoming User-Agent and checks whether it contains any of the known crawler patterns (twitterbot, facebookexternalhit, slackbot, and so on). A match on any single pattern is enough. There's no scoring or partial credit involved, and there's no allowlist of "known good" browsers to check against instead: everything that doesn't match a bot pattern is treated as a real user.

Because that pattern list is external, WarpLink keeps a built-in default list as a fallback. Each edge instance keeps the pattern list in memory, so detection adds no lookup to the redirect path. Pattern list updates reach every edge instance without a redeploy.

When to Use

You don't turn social previews on. Every link gets bot detection and the split response described above automatically, whether or not you've set any Open Graph fields. What you configure is what a bot sees once it's detected: set og_title, og_description, and og_image_url on a link when you want control over how it looks when shared, and leave them unset when you're fine letting the destination page's own meta tags do the work.

The two cases where this matters most in practice: a marketing campaign link where you want a specific headline and image regardless of what the landing page's own tags say, and a link into a mobile app screen (a deep link) that has no web page behind it at all, where the destination has no Open Graph tags of its own to fall back to. In that second case, setting OG fields on the link is the only way a shared app-only link gets a real preview instead of a blank card.

Worked Example

A crawler request and a real visitor hitting the exact same URL get genuinely different responses, not just different headers. Here's what a bot sees:

curl -A "facebookexternalhit/1.1" https://aplnk.to/abc123

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta property="og:title" content="Check out this product">
    <meta property="og:description" content="Amazing deal on...">
    <meta property="og:image" content="https://example.com/image.jpg">
    <meta property="og:url" content="https://aplnk.to/abc123">
    <meta property="og:type" content="website">
    <meta property="og:site_name" content="WarpLink">
    <meta name="twitter:card" content="summary_large_image">
    ...
  </head>
  <body>
    <script>window.location.replace("https://example.com/product")</script>
    <a href="https://example.com/product">Continue to https://example.com/product</a>
  </body>
</html>

And a real browser hitting the identical URL:

curl -A "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X)" https://aplnk.to/abc123

HTTP/1.1 302 Found
Location: https://example.com/product

The bot response includes a <script> redirect and a fallback link alongside the meta tags, so a crawler that happens to execute JavaScript, or a person who somehow lands on the HTML page directly, still ends up at the destination rather than stuck on an interstitial.

twitter:card is set to summary_large_image only when og_image_url is present, and falls back to the plain summary card otherwise, since a large-image card with no image is worse than a small one.

Troubleshooting

My link's preview shows the wrong title or image. Most social platforms cache a URL's preview the first time they see it, sometimes for days. If you change og_title, og_description, or og_image_url after the link has already been shared once, the platform may keep serving its cached card. Each platform has its own cache-busting tool (Facebook's Sharing Debugger, for example); WarpLink itself always serves the current values on every crawler request.

No preview shows up at all, just a bare link. Check that the User-Agent making the request is actually on the recognized pattern list. A crawler with an unusual or renamed User-Agent string won't be detected as a bot and will get a plain 302 like any other visitor, so no HTML card is ever generated for it to read.

The image doesn't render on some platforms. Confirm the image URL is reachable over HTTPS and is a JPEG or PNG. SVG images are frequently ignored by crawlers even though they load fine in a browser, which is the most common reason an image field is set correctly but nothing shows up.

A password-protected link's preview looks fine, but I expected it to be blocked too. That's expected, not a bug. Bots get the Open Graph card without ever seeing or needing the password, since a preview card carries no access to the underlying content. Only the redirect to the actual destination requires the password. See password protection for the full flow.

FAQ

Do I need to configure anything for social previews to work at all? No. Bot detection and the HTML/redirect split happen on every link automatically. Configuration only controls what the card says; it doesn't turn the feature on.

What happens if I don't set any OG fields on a link? A detected bot is redirected straight to the destination URL, the same 302 a real visitor gets, so the destination page's own Open Graph tags render instead of a generic WarpLink card.

Do detected crawlers count as clicks? Detected bots are excluded before a click is recorded, so a rich preview being generated for a known crawler never inflates your click count. See Link analytics for how the click count itself is computed.

Can I customize the HTML page a bot sees, beyond the OG and Twitter fields? The page structure is fixed. Title, description, and image are configurable per link.

Does a password-protected link still generate a social preview? Yes. See the troubleshooting note above: the preview card is served to bots without the password gate, since only the destination redirect is protected.

Related

• Deep linking: how WarpLink routes a link into your app
• Deferred deep links: preserve the destination through install
• Attribution: match installs back to the link that drove them
• Quickstart: create your first link in a few minutes
• The complete guide to deep linking: how Universal Links, App Links, and deferred deep links fit together end to end