# Custom social previews (Open Graph)

Source: https://developers.leonai.io/docs/guides/og-previews/

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:

| Field           | Purpose                                                |
| --------------- | ------------------------------------------------------ |
| `ogEnabled`     | Turn custom previews on for this link (`true`/`false`) |
| `ogTitle`       | The `og:title` shown as the card headline              |
| `ogDescription` | The `og:description` shown as the card subtitle        |
| `ogImage`       | Absolute 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.

## Enable on a link

```bash
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`):

```json
{
  "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`.

:::tip[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

| Status | When                                                                           |
| ------ | ------------------------------------------------------------------------------ |
| `400`  | `ogImage` is not a valid `http`/`https` URL, or a field exceeds its max length |

## Related

- [Links](https://developers.leonai.io/docs/guides/links/) — all other link fields
- [API Reference](https://developers.leonai.io/docs/api-reference/) — the full OpenAPI spec and Swagger UI