Paste a link into Discord and a card appears under it: site name, title, description, a coloured bar and maybe an image. That card is built from your page's HTML. You control almost all of it with a handful of meta tags, and the rules are documented by Discord.
How Discord fetches your page
- Discord makes one GET request for the URL and reads the HTML that comes back. Tags added later by JavaScript are never seen, so single-page apps need the tags in the server response.
- The response must be a 2xx with an HTML content type, not a download.
- It follows up to 5 redirects, reads up to 50 MB and gives up after 10 seconds, including measuring images.
The tags Discord reads
| Part of the card | Tag |
|---|---|
| Site name (small, above the title) | og:site_name |
| Title | og:title or twitter:title |
| Description | og:description or twitter:description |
| Image | og:image plus og:image:width and og:image:height |
| Coloured side bar | theme-color, a 6 or 8 digit hex such as #5865F2 |
| Layout | twitter:card and og:type |
A complete head for a normal page:
<meta property="og:site_name" content="Your Game">
<meta property="og:title" content="Join 4v4 nights every Friday">
<meta property="og:description" content="Patch notes, LFG and the community server.">
<meta property="og:image" content="https://yourgame.com/og.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta name="twitter:card" content="summary_large_image">
<meta name="theme-color" content="#E8590C">How the layout is chosen
| You set | Discord shows |
|---|---|
| Title, description and one image | Text with a small image to the side |
twitter:card = summary_large_image | Text with a large image underneath |
Two or more og:image tags | A gallery of up to 4 images |
og:type = video.other plus a video file | An inline player, using og:image as the poster |
Images can be PNG, GIF, JPG, WebP or AVIF. Give the width and height, or Discord downloads the image to measure it, which eats into the 10 second limit.
Limits
- Title: 70 bytes and 3 lines, then trimmed.
- Description: 350 bytes and 20 lines, then trimmed.
- Any URL over 2,048 characters, or a site name over 256 characters, means no preview at all.
- Only the first 5 links in a message get previews.
Common mistakes
- Relative image path without a slash. A relative
og:imagemust start with/. Absolute URLs are safest. - Tags only on the home page. People share deep links. Give every page its own title, description and image.
- Blocked fetches. Bot protection or a login wall in front of the page can stop Discord from reading it. If the debugger shows nothing, check your firewall rules for the request.
- Huge images. Measuring a slow, large image counts against the 10 second limit. Export the preview image at 1200 by 630 and compress it.
- Wrong colour format.
theme-colormust be a hex value. Named colours orrgb()are ignored.
Why your change does not show
Discord caches a preview for about 30 minutes. After you edit the tags, share the URL with a new query string such as ?v=2 to get a fresh fetch. To see exactly what Discord picked up, paste the URL into the Embed Debugger at discord.com/developers/embeds. Online "embed generators" and testers produce the same tags; the debugger is the one that shows Discord's own reading.
Your server's links too
The same rules apply to every page you link from your server: your rules page, your applications form, your verify page. A VaultCord verification page carries your server's branding, and on Premium and Plus it can run on your own domain, so the preview members see in your verify channel matches your site. Add a server widget or Login with Discord next, or start free.