Customizing Link Previews with URL Unfurling

When a URL is shared in chat, the URL Unfurler can display a rich preview (title, description, image, and optional price).

This guide explains:

How to enable or disable unfurling
How the unfurler selects metadata
How to control exactly what appears in previews
Common limitations and troubleshooting steps

How URL Unfurling Works

When a user sends an https:// link in a text message, the unfurler:

Fetches the page’s initial HTML
Reads supported meta tags
Builds a preview using the first matching tags by priority

The unfurler:

Reads only server-rendered HTML (no JavaScript execution)
Respects robots.txt
Caches results for ~1 hour per URL

Enable or Disable URL Unfurling

Unfurling is enabled by default in all SDKs.

To disable it:

val options = KustomerOptions.Builder()
    .setEnableUrlUnfurling(false)
    .build()

Kustomer.init(
    application = application,
    apiKey = "your-api-key",
    options = options
) {
    ...
}

Allowing the Unfurler via robots.txt

The unfurler respects your existing robots.txt.

If your site blocks crawlers, allow access explicitly:

User-agent: Kustomer-URL-Unfurler/1.0
Allow: /

Ensure:

Pages you want previewed are not disallowed
Image URLs are also accessible

Robots.txt changes may take up to 1 hour to propagate due to caching.

Controlling Preview Content

The unfurler reads metadata in a strict priority order.

If multiple tags are present, the first match wins.

Title Priority

kustomer:title
twitter:title
og:title
<title>

Description Priority

kustomer:description
twitter:description
og:description
<meta name="description">

Image Priority

kustomer:image
twitter:image
og:image
First <img> in HTML

Price Priority

kustomer:price:amount + kustomer:price:currency
product:price:amount + product:price:currency
og:price:amount + og:price:currency

When to Use Kustomer-Specific Tags

Use kustomer:* tags when you want chat previews to differ from social media previews.

Example:

<meta name="kustomer:title" content="Premium Wireless Headphones">
<meta name="kustomer:description" content="Free shipping. 2-year warranty.">
<meta name="kustomer:image" content="https://example.com/images/chat-preview.jpg">

If you want consistent previews across platforms, Open Graph tags are sufficient.

Example: Product Page With Custom Image and Price

<head>
  <title>Premium Wireless Headphones - TechStore</title>

  <meta name="description" content="High-quality wireless headphones with active noise cancellation.">

  <meta property="og:title" content="Premium Wireless Headphones">
  <meta property="og:description" content="Active noise cancellation. Free shipping.">
  <meta property="og:image" content="https://techstore.com/images/headphones-hero-1200x630.jpg">

  <meta property="product:price:amount" content="129.99">
  <meta property="product:price:currency" content="USD">
</head>

Preview result:

Title: Premium Wireless Headphones
Price: $129.99 (prepended if not already in title)
Description
Image

Controlling Price Display

If price meta tags are present, the unfurler prepends a formatted price to the title.

Example result:

$129.99 – Premium Wireless Headphones

Price Is NOT Added If:

The title already contains a price format such as:

$129.99
€50
49.99 EUR

Valid Ways to Provide Price

Kustomer tags (highest priority)

<meta name="kustomer:price:amount" content="129.99">
<meta name="kustomer:price:currency" content="USD">

Open Graph (recommended standard)

<meta property="product:price:amount" content="129.99">
<meta property="product:price:currency" content="USD">

Legacy Open Graph

<meta property="og:price:amount" content="129.99">
<meta property="og:price:currency" content="USD">

Requirements:

Use ISO 4217 currency codes (USD, EUR, GBP)
Provide both amount and currency
Do not rely on JSON-LD or Schema.org (not supported)

Image Requirements

For best results:

Minimum size: 1200 × 630 px
Format: JPEG or PNG
Must be publicly accessible
Must not require authentication
Must be included in initial HTML

Images added dynamically via JavaScript will not be detected.

Minimal Supported Page

At minimum, a page must include:

<title>Page Title</title>
<meta name="description" content="Short description.">

Without og:image or similar tags, previews will not include an image.

Limitations

Only https:// URLs are supported
Only the first 5 URLs in a single message are unfurled
Only text messages trigger unfurling (not structured templates)
Page must respond within 5 seconds
HTML payload must be ≤ 1MB
Preview data is cached per URL for ~1 hour
Previews are ephemeral and typically visible for ~60 days in real-time channels
Pages with <meta name="robots" content="noindex"> will not be unfurled

If unfurling fails, the message still sends without a preview.

Troubleshooting

No Preview Appears

Check:

enableUrlUnfurling is true
URL begins with https://
Page responds in under 5 seconds
HTML size is ≤ 1MB
Meta tags exist in initial HTML
URL is within first 5 links in message
robots.txt allows Kustomer-URL-Unfurler/1.0
Page does not contain noindex

Preview Shows Wrong Image or Title

Review tag priority order
Remove conflicting tags
Confirm correct tag values
Wait up to 1 hour for cache refresh

Price Not Displayed

Provide both amount and currency
Use supported tag names
Ensure title does not already contain a formatted price

Summary

To control link previews:

Ensure metadata is server-rendered
Use Kustomer-specific tags if chat previews should differ from social previews
Provide explicit image and price tags for product pages
Verify robots.txt and HTTPS accessibility
Allow for cache delay when testing changes

For additional support, contact Kustomer Support.