Link embeds and bot embeds are different things
Two things in Discord are called embeds. When someone pastes a URL into chat, Discord fetches the page and draws a card under the message. Discord's developer docs call that card a link preview and the process unfurling. Bots and webhooks can also post embeds they build themselves from fields such as title, color and footer. The Message Resource reference lists the embed types: rich is the generic embed built from attributes, and it is always the type for webhook embeds, while link, article, image, video and gifv cover previews of links and media.
This guide is about the first kind: what your site's tags make Discord show. Nothing here needs a bot. For the same job on other networks, start at the Open Graph hub.
How does Discord read your page?
The Link Previews page in Discord's developer documentation, as published in November 2026, says Discord makes a single GET request for the shared URL and parses the HTML that comes back. A preview appears only if all of these hold:
- The page is HTML served over HTTP or HTTPS.
- The tags are in the HTML your server sends. No code is executed, so tags added by a script after load are never seen.
- The response is a 2xx status.
- The content type is
text/htmlorapplication/xhtml+xml, and the page is not served as a download. - There are at most 5 redirects and at most 50 MB of data.
- The whole fetch, including measuring your images and video, finishes within 10 seconds.
The same page does not name the user agent Discord's fetcher sends, and we did not find it in the other official pages we read. If a firewall rule is blocking previews, check your server log for the request made when you paste a link, rather than trusting a user agent string from a third party.
Which tags does Discord read?
Discord takes the key from name if present, otherwise from property, and key names are case sensitive. When several tags map to the same field, the first non-empty one wins for title, description and site name; for layout, color and date tags, the last one in the document wins.
| Tag | Embed field | Notes from Discord's docs |
|---|---|---|
| og:title, twitter:title | Title | Trimmed past 70 bytes or 3 lines |
| og:description, twitter:description | Description | Plain text; trimmed past 350 bytes or 20 lines |
| title element plus meta description | Title and description | Used only as a pair, and only when no og or twitter title or description exists |
| og:site_name | Provider name above the title | Over 256 characters means no preview at all |
| og:image, twitter:image | Image or thumbnail | png, gif, jpg, jpeg, webp, avif |
| og:image:width, og:image:height | Image dimensions | Without them, Discord fetches the image to measure it |
| twitter:card | Layout | summary_large_image, photo and player change the layout |
| og:type | Layout | Only rich, video, video.* and instapp:photo are read |
| theme-color | Accent color | #RRGGBB or #RRGGBBAA only |
| og:pubdate | Timestamp | Full RFC 3339 with time and offset |
| oEmbed link (JSON) | Gap filler and author line | Runs after Open Graph; the only way to add an author |
A head that gives a large image card with a colored accent looks like this. It mirrors the quick start block in Discord's docs, with our example values.
<meta property="og:site_name" content="Example Town Journal">
<meta property="og:title" content="Why the town clock runs slow">
<meta property="og:description" content="A 140 year old escapement and a repair that took three attempts.">
<meta property="og:image" content="https://example.com/wp-content/uploads/town-clock-1200x630.jpg">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta name="theme-color" content="#1F6FEB">
<meta name="twitter:card" content="summary_large_image">Check which of these your SEO plugin already prints. theme-color is not an Open Graph tag, so it may come from your theme or from nowhere; if the theme prints one, Discord uses it. The summary_large_image card markup guide explains the twitter line, and choosing the share image size covers the 1200 by 630 crop.
Which layout will my link get?
| What the page has | What Discord shows |
|---|---|
| Title, description, one image, no layout tags | Text with a small image |
| twitter:card set to summary_large_image | Text with a large image below it |
| twitter:card set to photo, or a URL straight to an image file | The image on its own, no description |
| og:type video.other or twitter:card player, plus a video file | An inline player using og:image as the frame |
| Two or more og:image tags | A gallery of up to 4 images |
| og:type set to rich | Description rendered as Discord markdown with a small thumbnail |
The second row is the one most sites want, and it is why a site with perfect Open Graph tags can still get a small thumbnail on Discord: the twitter:card line is missing.
How do you test a Discord embed?
Read your own source
Open the page logged out, view source, and search for
og:,twitter:cardandtheme-color. To see a rendered card without posting, paste the HTML into the browser-based preview checker; it fetches nothing.Check the response
Run
curl -sI https://example.com/town-clock/. Look for a 2xx status, atext/htmlcontent type, and noContent-Disposition: attachmentheader.Open the Embed Debugger
Go to
discord.com/developers/embeds, the Embed Debugger linked from the Link Previews page, and paste your URL. It shows which tags Discord picked up and which layout it chose.Post with a fresh query string
In a test channel, paste the URL with
?v=2on the end. Discord's docs recommend this to see changes at once while the old preview is cached.Compare with the plain URL
After about 30 minutes, paste the canonical URL without the query string and confirm it now matches.
How do you refresh a cached Discord embed?
Discord caches previews for about 30 minutes. While a preview is cached, editing your tags and sharing the same URL again shows the old card. The documented workaround is a new query string, such as ?v=2, which Discord treats as a new URL. Purge your own page cache first, or Discord will fetch the old HTML from it. Discord's docs do not say whether embeds on messages posted before the change are updated later, so do not promise that to anyone.
How do you hide or turn off embeds?
- One link. The Help Center article How do I disable auto-embed? says to wrap the link in
< >, for example<https://example.com/town-clock/>. The link stays clickable without a card. - For yourself. The same article says: click the User Settings cog in the bottom left, select the Text & Images tab, and uncheck When posted as links to chat and When uploaded directly to Discord. If your client does not show a Text & Images tab, look for those two checkbox labels elsewhere in User Settings.
- From a bot. The Message Resource reference lists a
SUPPRESS_EMBEDSflag. A bot can set it when creating a message, and the Edit Message endpoint can set or unset it later. Users other than the author can change flags only with the Manage Messages permission.
Why is my Discord embed not showing?
| Symptom | Likely cause in Discord's docs | Fix |
|---|---|---|
| No preview at all | Tags added by JavaScript, a non 2xx response, or a fetch over 10 seconds | Print tags server side; speed up the page and image |
| No preview at all | og:site_name over 256 characters, or a URL over 2,048 characters | Shorten the value |
| Small thumbnail instead of a large image | No twitter:card summary_large_image | Add the twitter:card line |
| Old title or image after an edit | The 30 minute cache | Test with ?v=2, or wait |
| Gallery of images you did not expect | Two or more og:image tags | Keep one og:image |
| Accent color ignored | theme-color not in 6 or 8 digit hex | Use #RRGGBB |
| Only some links in a message preview | More than 5 links per message | Split the message |
| HTML tags shown in the description | Descriptions are plain text unless og:type is rich | Strip markup from og:description |
What goes wrong
- Duplicate tags from a theme and a plugin. Discord's first-wins and last-wins rules can give you one plugin's title and the other plugin's layout or color. Remove one source, as in the duplicate tag cleanup list.
- Dimension tags on the wrong image tag. Width, height, type and alt attach to og:image and twitter:image only, not to og:image:secure_url. Use the plain tag names.
- A slow image host. Without width and height tags Discord downloads the image to measure it, and that counts against the 10 second fetch.
- A bot protection challenge. A rule that challenges unknown clients returns a non HTML or non 2xx response, and no preview appears.
- Testing the same URL again and again. Inside the cache window every paste shows the old card. Use the query string trick, and read Slack's unfurling rules if the same link also misbehaves there.
Check it worked
- View source shows one og:title, one og:image with width and height, one twitter:card set to summary_large_image, and one theme-color in hex.
- curl shows a 2xx status and a text/html content type for the page.
- The Embed Debugger lists your tags and reports the large image layout.
- A test post with ?v=2 shows the large image, your title and the accent color.
- After 30 minutes the plain URL shows the same card.
Sources
- Discord Developer Documentation, Link Previews (fetched November 2026)
- Discord Developer Documentation, Message Resource: embed object and message flags (fetched November 2026)
- Discord Help Center, How do I disable auto-embed? (fetched November 2026)
Questions
What meta tags does Discord use for embeds?
Discord reads og:title, og:description, og:site_name and og:image, with twitter equivalents as fallbacks. twitter:card sets the layout, theme-color sets the accent color, and a JSON oEmbed link can fill gaps and add an author line.
How do I make a Discord embed show a large image?
Add a meta tag with name twitter:card and content summary_large_image, alongside og:image. Without it, Discord's docs say a title, description and single image produce text with a small image.
How do I change the color of a Discord embed?
Add a theme-color meta tag with a 6 or 8 digit hex value, such as #1F6FEB. Discord's docs say other formats are not read, and the last theme-color tag in the document wins.
How long does Discord cache link previews?
About 30 minutes, according to Discord's Link Previews documentation. To see a change at once, share the URL with a new query string such as ?v=2, or check it in the Embed Debugger.
What user agent does Discord use to fetch link previews?
Discord's Link Previews documentation does not name one. It describes a single GET request that runs no scripts and must finish within 10 seconds. Check your server log when you paste a link to see the request.
Hannah Voss, Editor. Checks every guide against a working WordPress install and the networks' current documentation. Last reviewed September 2026.
Related reading
- Slack link preview: how unfurling works and how to fix itHow Slack builds a link preview: the tags its robot reads, its user agent, the 30 minute cache, how to test, remove or block a preview, and why one fails.10 min read
- Twitter cards on X: tags and testingSet up Twitter card tags so links to your WordPress posts show a large image on X: the summary_large_image card, fallbacks to Open Graph, sizes and testing.6 min read
- Open Graph image size: 1200 by 630 and the safe zoneThe right Open Graph image size is 1200 by 630 pixels at a 1.91:1 ratio. Minimums, file limits, formats, and a centre safe zone for square crops.6 min read
- Link preview checker: test your Open Graph and card tagsPaste a page's HTML to check its Open Graph and X card tags, see mock previews, and find duplicate, missing or relative tags. Runs in your browser only.10 min read