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 — The Worker returns a full HTML page with Open Graph and Twitter Card meta tags
2. Real user — The Worker 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

The Worker checks the User-Agent against a list of known bot patterns stored in KV (_config:bot-agents). 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, the Worker 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_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 uses the destination URL's existing OG tags as fallback.

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