Slack Link Preview: How Unfurling Works
When you paste a URL into Slack, it “unfurls” the link by fetching Open Graph meta tags and displaying a preview card. This guide explains how Slack unfurling works, what tags you need, and how to troubleshoot issues.
How Slack Unfurling Works
Slack’s link unfurler (user agent: Slackbot-LinkExpanding) fetches the URL, reads Open Graph meta tags, and renders a preview card in the channel.
The unfurl card displays: site name (from og:site_name), page title (from og:title), description (from og:description), and an image (from og:image).
Slack unfurls links automatically in public channels. In direct messages and private channels, the sender may need to click “Show preview” for certain URLs.
Required and Recommended Tags
Slack reads the same OG tags as other platforms. For a complete unfurl, include:
Required: og:title (page title for the unfurl card). Without it, Slack falls back to the <title> tag.
Recommended: og:description (text below the title, truncated at about 300 characters), og:image (preview image, displayed below the text), og:site_name (label above the title), og:url (canonical URL).
Slack also reads Twitter Card tags as fallback. If og:title is missing, Slack tries twitter:title.
<!-- Tags for Slack link unfurling -->
<meta property="og:title" content="Your Page Title" />
<meta property="og:description" content="A concise description of the page content." />
<meta property="og:image" content="https://example.com/og-image.jpg" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:url" content="https://example.com/page/" />
<meta property="og:site_name" content="Example" />
<meta name="twitter:card" content="summary_large_image" />Image Requirements
Slack’s image handling is similar to other platforms:
Recommended size: 1200 x 630 pixels (1.91:1 ratio) for large previews.
Minimum size: 200 x 200 pixels. Images below this size may not be displayed.
Maximum file size: Images over 5 MB may not be fetched. Keep images under 2 MB for reliable display.
Formats: JPEG, PNG, GIF, and WebP. GIFs display as static images (first frame).
HTTPS required: Slack only fetches images from HTTPS URLs.
Unfurling Behavior and Limits
Rate limiting: Slack limits unfurl requests. If many links are posted rapidly, some may not unfurl. This is primarily an issue in busy channels with bots posting multiple links.
Caching: Slack caches unfurled content. Updates to your OG tags may take up to 1 hour to reflect in new unfurls. Previously unfurled links in existing messages do not update automatically.
Authentication: Slack’s crawler does not send cookies or authentication headers. If your page requires login, Slack cannot unfurl it. Ensure that OG tags are visible to unauthenticated requests.
Redirects: Slack follows up to 3 redirects. Long redirect chains may prevent unfurling.
Response time: Slack’s crawler has a timeout of approximately 3 seconds. If your server takes longer to respond, the unfurl fails.
Custom Unfurling via Slack API
Slack also supports custom unfurling through the Events API. This lets Slack apps control how specific domains are displayed. When a link from your domain is posted, your app receives an event and can respond with a custom unfurl payload.
Custom unfurling is useful for internal tools, dashboards, and SaaS products where the standard OG-based preview is insufficient. The custom unfurl can include formatted text, buttons, and interactive elements.
Troubleshooting Slack Unfurling
Link not unfurling at all: Check that Slackbot can reach your server. Test with curl -A Slackbot-LinkExpanding https://yoursite.com/page/. Verify your robots.txt does not block Slackbot.
Image not showing: Verify the og:image URL uses HTTPS and responds within 3 seconds. Check that the image is under 5 MB and uses a supported format.
Stale preview after update: Slack caches unfurls for up to 1 hour. New messages with the same URL will eventually show the updated preview. You cannot force a re-fetch of an already-unfurled link in an existing message.
Unfurl shows wrong content: Verify your page returns consistent OG tags. Server-side rendering issues or A/B testing frameworks may serve different content to Slackbot than to browsers.
Unfurling disabled by workspace admin: Workspace admins can disable link previews for specific domains or globally. If your links do not unfurl in a specific workspace, check with the workspace administrator.
Slack vs. Other Platforms
Faster than Facebook, slower than Discord: Slack’s cache lasts about 1 hour. Facebook caches for up to 30 days. Discord refreshes within minutes.
Strict timeout: Slack has a ~3 second timeout for fetching pages, stricter than most other platforms.
Custom unfurling API: Slack is the only major platform that offers an API for custom link previews.
Workspace settings: Unlike other platforms, Slack allows workspace admins to control unfurling behavior per domain.
FAQ
Slack caches unfurled content for up to 1 hour. New messages with the same URL will show updated OG data after the cache expires. Already-posted messages retain the original unfurl.
There is no public cache-clearing tool for Slack. You can delete and re-post the message, or append a query parameter to the URL (e.g., ?v=2) to force a fresh unfurl.
This typically means Slack's crawler could not reach your page within its ~3 second timeout, your robots.txt blocks Slackbot, or your server requires authentication. Test with curl -A Slackbot-LinkExpanding to diagnose.
Slack supports video unfurling from whitelisted providers (YouTube, Vimeo, etc.). Direct video URLs in og:video from other sources are displayed as static image previews.
Yes. Workspace admins can disable link previews globally or for specific domains in Workspace Settings > Permissions. If your links are not unfurling in a specific workspace, this may be the cause.