Discord Link Preview: How Embeds Work & Troubleshooting
Discord generates link embeds from Open Graph meta tags. When you paste a URL into a Discord message, Discord’s crawler fetches the page and creates a rich embed card. This guide covers how it works, what tags you need, and how to fix issues.
How Discord Embeds Work
When a user posts a URL in a Discord channel, Discord’s crawler (Discordbot) fetches the page and reads its Open Graph meta tags. It uses these tags to build a rich embed card directly in the chat.
Discord reads the standard OG tags: og:title, og:description, og:image, og:url, and og:site_name. It also reads og:type and Twitter Card tags as fallback for certain fields.
The embed appears as a card with a colored left border, site name, title, description, and an optional image. The border color is derived from the theme-color meta tag if present.
Required and Recommended Tags
Required for a basic embed: og:title and og:description. Without these, Discord may not generate an embed at all or use the page’s <title> tag as fallback.
Recommended for a complete embed: og:image for a visual preview, og:site_name for the site label above the title, og:url for the canonical URL, and og:type to define the content type.
Discord-specific: The <meta name="theme-color" content="#hex"> tag controls the left border color of the embed. This is not an OG tag but Discord reads it.
<!-- Minimal Discord embed -->
<meta property="og:title" content="Your Page Title" />
<meta property="og:description" content="A short description of your content." />
<meta property="og:image" content="https://example.com/image.jpg" />
<meta property="og:url" content="https://example.com/page/" />
<meta property="og:site_name" content="Example" />
<meta name="theme-color" content="#5865F2" />Image Requirements
Discord supports two image display modes depending on the image dimensions and the twitter:card value.
Large image (below text): Set twitter:card to summary_large_image. The OG image appears as a large preview below the title and description. Recommended size: 1200 x 630 pixels (1.91:1 aspect ratio).
Small thumbnail (right side): Set twitter:card to summary or omit it. The image appears as a small square thumbnail on the right side of the embed. Size: at least 200 x 200 pixels.
Supported formats: JPEG, PNG, GIF (first frame only), and WebP. Maximum file size: 8 MB. Images must be served over HTTPS.
<!-- Large image embed -->
<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 name="twitter:card" content="summary_large_image" />
<!-- Small thumbnail embed -->
<meta property="og:image" content="https://example.com/icon.png" />
<meta name="twitter:card" content="summary" />Embed Limits and Behavior
Title: Truncated at approximately 256 characters.
Description: Truncated at approximately 350 characters. Longer text is cut with an ellipsis.
Site name: Displayed above the title in small, colored text.
Multiple links: Discord generates one embed per URL. If a message contains multiple URLs, each gets its own embed (up to 5 per message).
Video embeds: Discord supports og:video for inline video playback from whitelisted providers (YouTube, Vimeo, Twitch, etc.). Other video URLs are displayed as static image embeds.
Caching: Discord caches embeds, but the cache duration is shorter than Facebook’s (minutes to hours, not weeks). If you update your OG tags, the embed typically refreshes within a few minutes for new shares.
The theme-color Meta Tag
The theme-color meta tag lets you customize the colored left border of the Discord embed. This is a standard HTML meta tag, not an Open Graph tag.
<!-- Discord embed border color -->
<meta name="theme-color" content="#FF5733" />If theme-color is not set, Discord uses a default gray border. The color applies to the left edge of the embed card.
You can use any valid hex color. Some sites match it to their brand color for consistent appearance across platforms.
Troubleshooting Discord Embeds
No embed appears: Discord’s crawler may be blocked by your server. Check your robots.txt — Discordbot must not be disallowed. Also verify that your server responds to the user agent Discordbot.
Wrong image: Discord may cache a previous version. Append a query parameter to force a fresh fetch (e.g., example.com/page/?v=2). Also check that og:image uses an absolute HTTPS URL.
Image not showing: Verify the image URL is accessible, under 8 MB, and uses a supported format. Self-signed SSL certificates will cause the image fetch to fail.
Stale embed after update: Discord caches embeds per URL. Edit the message or re-paste the link to trigger a re-fetch. In bot contexts, you can use the suppress_embeds flag to remove and re-add embeds.
Embed appears but looks wrong: Use the Open Graph Debugger to verify your tags are correctly set. The source code in the <head> section should contain all required meta tags.
Discord vs. Other Platforms
Discord’s embed behavior differs from other platforms in several ways:
Faster cache refresh: Unlike Facebook (which caches for up to 30 days), Discord refreshes embeds within minutes.
theme-color support: Discord is the only major platform that uses the theme-color meta tag for embed styling.
Bot embeds: Discord bots can create custom rich embeds via the API with fields, footers, authors, and multiple images — these are separate from OG tag-based link previews.
Link previews in Discord are similar to Slack and WhatsApp in that they all read OG tags, but each platform has its own rendering quirks.
FAQ
Yes. Discord reads twitter:card to determine the image layout (large image vs. small thumbnail). It also falls back to twitter:title and twitter:description if the corresponding OG tags are missing.
Discord does not have a public cache-clearing tool like Facebook's Sharing Debugger. The fastest method is to append a unique query parameter to the URL (e.g., ?v=2) to force a fresh fetch. Embeds also refresh automatically within a few minutes.
Discord uses a small thumbnail layout by default. To get a large image below the text, add <meta name="twitter:card" content="summary_large_image"> to your page.
Discord supports GIF images in embeds, but only the first frame is displayed as a static image in the embed card. Animated GIFs do not play in OG-based embeds (they do work in bot-generated embeds).
Discord supports inline video playback only from whitelisted providers like YouTube, Vimeo, and Twitch. For other video URLs, Discord displays the og:image as a static preview instead.