Skip to main content

Custom social previews (Open Graph)

When a short link is pasted into WhatsApp, Slack, X/Twitter, Facebook, iMessage, or any app that unfurls links, the app's crawler fetches the URL to build a preview card. With custom social previews you control exactly what that card shows — title, description, and image — without sacrificing redirect speed for real visitors. Requires links:write. Available on all tiers.

Set four fields on a link:

FieldPurpose
ogEnabledTurn custom previews on for this link (true/false)
ogTitleThe og:title shown as the card headline
ogDescriptionThe og:description shown as the card subtitle
ogImageAbsolute URL of the og:image thumbnail

How it works​

The redirect endpoint inspects the request's User-Agent:

  • Crawlers / bots (WhatsApp, Twitterbot, facebookexternalhit, Slackbot, etc.) receive a lightweight HTML page containing the Open Graph and Twitter Card <meta> tags — so the unfurl renders your custom card.
  • Humans get the normal fast 302 redirect to the destination. Preview generation never slows down real clicks.
curl -X POST https://api.short.leonai.io/api/v1/links \
  -H "X-API-Key: $LEONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "longUrl": "https://example.com/spring-sale",
    "ogEnabled": true,
    "ogTitle": "Spring Sale — 40% off",
    "ogDescription": "This weekend only. Free shipping over $50.",
    "ogImage": "https://cdn.example.com/spring-sale.png"
  }'

Response (201 Created):

{
  "success": true,
  "data": {
    "id": "link_...",
    "shortUrl": "https://short.leonai.io/a1b2c3",
    "ogEnabled": true,
    "ogTitle": "Spring Sale — 40% off",
    "ogDescription": "This weekend only. Free shipping over $50.",
    "ogImage": "https://cdn.example.com/spring-sale.png"
  }
}

You can also add or change these fields later with PATCH /api/v1/links/:id.

Test your unfurl

Because previews are User-Agent gated, opening the short URL in a browser shows the redirect, not the card. Validate with a crawler-facing tool (e.g. paste the link into a chat app, or a card validator) after enabling ogEnabled.

Error codes​

StatusWhen
400ogImage is not a valid http/https URL, or a field exceeds its max length