Rich link previews

Send a link part to render a URL as a native preview card.

Send a preview

curl -sS -X POST "https://api.relayapp.im/v1/messages" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: link-evt_01JZE9M2XW" \
  -d '{
    "chat_id": "cnv_01JZC7K4RQ",
    "parts": [{
      "type": "link",
      "url": "https://example.com/article"
    }]
  }'

Constraint	Value
Scheme	HTTPS
Maximum length	2,048 characters

Add context before the card

Relay preserves part order, so a preview can follow text in the same send:

{
  "parts": [
    { "type": "text", "text": "This is the source I used:" },
    { "type": "link", "url": "https://example.com/article" }
  ]
}

That is one message with two parts, in the order you sent them. A reply or a reaction targets the message, and can name one part of it.

What a link part stores

A link part keeps two things: the URL, and the page title.

{ "part_index": 0, "type": "link", "url": "https://example.com/article", "title": "The article" }

Everything else a card draws — the description, the hero image, the site name — is live detail rather than stored content. Fetch it with GET /v1/links/unfurl when you render:

curl -sS "https://api.relayapp.im/v1/links/unfurl?url=https%3A%2F%2Fexample.com%2Farticle" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"

Relay fetches the page itself and caches the result, so no recipient opens a connection to a URL somebody else chose, and the hero image comes back as a Relay URL rather than the publisher’s own image host. The older sender-resolved preview fields (description, site_name, image_url, canonical_url, preview_kind, preview_version, attachment_id, mime_type, filename, size_bytes, width, height, blur_hash) are still accepted on a send, so existing integrations keep working, but they are not stored and not echoed back.

Let Relay resolve the title

Send preview_state: "pending" when you have not read the page yourself:

{ "type": "link", "url": "https://example.com/article", "preview_state": "pending" }

The message commits immediately with the part marked pending. Relay fetches the page and then emits a message.updated event carrying the settled title. This always settles — a page with no title clears the marker too — so a pending part is a preview that is coming, never one that silently failed. A settled part carries no preview_state key at all.

Fallback

Destination	Card
Public page with a title	✅ Preview card with the title, plus whatever the unfurl adds
Page that blocks metadata requests, sits behind auth, or is on a private network	⚠️ Simpler card showing the host and URL

The server never rewrites or shortens the destination.

Choosing the part type

Part	Use when
`text`	The URL is ordinary message text
`link`	The card itself is intentional

Rich previews use normal message behavior: the same response, history, events, idempotency, replies, reactions, and delivery and read receipts.

Next steps

Sending messages for every part type
Reactions for targeting one part

Start here

Send

Receive

Connect what you already run

Reference

Relay for Business

About Relay

Rich link previews

Send a preview

Add context before the card

What a link part stores

Let Relay resolve the title

Fallback

Choosing the part type

Next steps

​Send a preview

​Add context before the card

​What a link part stores

​Let Relay resolve the title

​Fallback

​Choosing the part type

​Next steps

Send a preview

Add context before the card

What a link part stores

Let Relay resolve the title

Fallback

Choosing the part type

Next steps