OG
OGProof
Guide7 min read

Discord Open Graph Tags: How Link Previews Work and How to Fix Them

How Discord generates link preview embeds from Open Graph tags — what Discordbot reads, image requirements, the theme-color embed accent, caching, and how to validate your setup.

When you paste a URL into a Discord message, Discord's bot fetches the page and generates an embed — the coloured card that appears below your message with a title, description, image, and optional accent colour. These embeds are built from Open Graph meta tags. Get the tags right and your links look polished in every server. Get them wrong and the embed is blank, broken, or missing the image entirely.

How Discord's Link Preview System Works

Discord's crawler is called Discordbot. It makes an HTTP GET request to your page using the user-agent string Discordbot/2.0 (+https://discordapp.com/), reads the raw server-rendered HTML, and extracts Open Graph meta tags. Like all social crawlers, Discordbot does not execute JavaScript — so any OG tags injected by React, Vue, or other client-side frameworks after page load are invisible to it.

Discordbot crawls pages on demand — the first time a URL is pasted in any Discord channel. It caches the result for approximately 30 minutes, which is much shorter than Facebook or LinkedIn. After the cache expires, the next paste of the same URL triggers a fresh crawl.

Tags Discord Reads

Discord reads a combination of og: namespace tags and a special HTML meta tag for embed colour:

  • —og:title — the bold title at the top of the embed. Discord shows up to ~256 characters.
  • —og:description — the body text below the title. Discord shows up to ~2048 characters, but keep it under 300 for readability.
  • —og:image — the preview image. Discord shows this as a large image card when dimensions meet requirements.
  • —og:site_name — appears as a small label above the title.
  • —og:url — used as the link destination and canonical identifier for the embed.
  • —og:type — Discord reads this but does not alter embed layout based on type.
  • —theme-color — a <meta name="theme-color" content="#hexcolor" /> tag that sets the coloured left-border accent on the Discord embed. This is not an og: tag.
TipThe theme-color meta tag is Discord's most distinctive feature. Set it with <meta name="theme-color" content="#7c3aed" /> and Discord renders a coloured vertical bar on the left edge of the embed in your chosen hex colour. No other major platform reads this tag for embed styling.

Minimum Required Tags for a Discord Embed

<!-- Minimum for a Discord embed with image -->
<meta property="og:title" content="Your Page Title" />
<meta property="og:description" content="A concise 1–2 sentence summary." />
<meta property="og:image" content="https://example.com/og-image.jpg" />

<!-- Optional but recommended -->
<meta property="og:url" content="https://example.com/your-page" />
<meta property="og:site_name" content="Your Brand" />
<meta name="theme-color" content="#5865F2" />

Full Recommended Tag Set for Discord

<!-- Complete OG setup for Discord embeds -->
<meta property="og:title" content="Your Page Title" />
<meta property="og:description" content="A compelling summary shown in the embed body." />
<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:image:alt" content="Descriptive alt text" />
<meta property="og:url" content="https://example.com/your-page" />
<meta property="og:type" content="website" />
<meta property="og:site_name" content="Your Brand Name" />

<!-- Discord embed accent colour — not an og: tag -->
<meta name="theme-color" content="#5865F2" />

Discord Image Requirements

Discord's image handling has a few quirks compared to other platforms:

  • —Recommended size: 1200×630px (1.91:1 aspect ratio) — renders as a large image card below the embed text.
  • —Minimum: no hard minimum, but images below 80×80px may not display.
  • —Protocol: HTTPS required — Discord does not load HTTP image URLs.
  • —Formats: JPEG, PNG, GIF, and WebP are all supported. Discord renders animated GIFs.
  • —Max file size: 8MB. Larger images are not displayed.
  • —CDN-hosted images load faster — Discord fetches the image URL directly when rendering the embed.
  • —Square images (1:1) are displayed as a small thumbnail to the right of the text rather than a large card.
TipDiscord supports animated GIF og:images. If you set og:image to an animated .gif URL with HTTPS, Discord will display the animation in the embed. This is unique among major social platforms — Twitter, LinkedIn, and Facebook do not animate GIF OG images.

The theme-color Tag in Detail

Discord's embed colour accent is controlled by the standard HTML theme-color meta tag, originally designed for browser UI theming. Discord co-opted it as an embed styling signal. The value must be a valid hex colour (3 or 6 digits, with #):

<!-- Sets Discord embed left-border to Discord's blurple -->
<meta name="theme-color" content="#5865F2" />

<!-- Brand purple -->
<meta name="theme-color" content="#7c3aed" />

<!-- Brand red -->
<meta name="theme-color" content="#dc2626" />

<!-- Works with 3-digit shorthand too -->
<meta name="theme-color" content="#fff" />

If theme-color is absent, Discord renders the embed with a default grey/dark accent bar. Setting it to your brand colour makes shared links immediately recognisable in Discord servers.

Discord's Caching Behaviour

Discord caches embed data for approximately 30 minutes per URL. This is significantly shorter than Facebook (30 days) or LinkedIn (7 days). In practice this means:

  • —If you fix your OG tags, the corrected embed will appear for new pastes within ~30 minutes without any manual action.
  • —During the cache window, users in other servers may see the old (broken) preview.
  • —There is no official Discord tool to force a cache purge — you wait for natural expiry.
  • —Adding a cache-busting query string to the URL (e.g. ?v=2) forces Discord to treat it as a new URL and crawl it immediately.

Discord OG Tags in Next.js

In Next.js App Router, use the Metadata API for og: tags and a separate themeColor property for the Discord accent colour:

// app/layout.tsx or app/[page]/page.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'Your Page Title',
  description: 'A concise summary.',
  // Sets <meta name="theme-color" content="..." /> — Discord reads this
  themeColor: '#5865F2',
  openGraph: {
    title: 'Your Page Title',
    description: 'A concise summary.',
    url: 'https://example.com/your-page',
    siteName: 'Your Brand',
    type: 'website',
    images: [
      {
        url: 'https://example.com/og-image.jpg',
        width: 1200,
        height: 630,
        alt: 'Your Page Title',
      },
    ],
  },
}

Next.js renders themeColor as <meta name="theme-color" content="..." /> in the document head, which is exactly what Discord reads for the embed accent colour. The openGraph fields map directly to the og: namespace tags.

Discord Video Embeds

Discord supports video embeds using the og:video tags. When og:video is present with a valid direct video URL, Discord renders an inline playable video in the embed instead of a static image:

<!-- For inline video playback in Discord -->
<meta property="og:type" content="video.other" />
<meta property="og:video" content="https://example.com/video.mp4" />
<meta property="og:video:width" content="1280" />
<meta property="og:video:height" content="720" />
<meta property="og:video:type" content="video/mp4" />
<!-- Still include og:image as poster/thumbnail -->
<meta property="og:image" content="https://example.com/og-image.jpg" />

The video URL must point to a direct .mp4 or .webm file (not a YouTube or Vimeo page URL). Discord will render the video inline if the MIME type matches and the URL is accessible without authentication.

How to Verify What Discord Sees

There is no official Discord embed debugger tool. You can simulate what Discordbot reads using curl:

# Fetch your page as Discordbot and extract OG tags
curl -s -A "Discordbot/2.0 (+https://discordapp.com/)" \
  "https://example.com/your-page" | grep -iE '(og:|theme-color)'

# Expected output for a well-configured page:
# <meta property="og:title" content="Your Title" />
# <meta property="og:description" content="Your description." />
# <meta property="og:image" content="https://example.com/og.jpg" />
# <meta property="og:image:width" content="1200" />
# <meta property="og:image:height" content="630" />
# <meta property="og:url" content="https://example.com/your-page" />
# <meta name="theme-color" content="#5865F2" />

# If this returns nothing: OG tags are missing from server HTML
# (likely injected by JavaScript, which Discordbot ignores)

OGProof simulates the Discordbot crawl automatically — it sends requests using the Discordbot/2.0 user-agent, parses the returned HTML, and renders an accurate preview of what your Discord embed will look like, including the theme-color accent bar. It flags missing tags, non-HTTPS image URLs, and image dimension issues with specific remediation instructions.

Common Discord OG Tag Mistakes

  1. 1.OG tags injected by JavaScript — Discordbot does not execute JavaScript. All tags must be in server-rendered HTML.
  2. 2.HTTP og:image URL — Discord will not load the image. Use HTTPS.
  3. 3.Missing theme-color — embed renders with a plain grey accent instead of your brand colour.
  4. 4.Image file too large (over 8MB) — Discord silently drops the image and shows a text-only embed.
  5. 5.Relative og:image URL — Discord cannot resolve relative paths. Always use an absolute URL.
  6. 6.Wrong content type — og:image pointing to an HTML page instead of an image file causes no preview.
  7. 7.Forgetting og:site_name — without it, Discord shows only the domain as the embed header rather than your brand name.

Discord OG Tag Checklist

  • —og:title — present, concise (under 256 characters)
  • —og:description — present, under 300 characters for readability
  • —og:image — absolute HTTPS URL, 1200×630px recommended, under 8MB
  • —og:image:width and og:image:height — always include for correct layout selection
  • —og:url — set to the canonical URL of the page
  • —og:site_name — your brand name
  • —theme-color — set to your brand hex colour for the Discord embed accent bar
  • —OG tags must be in server-rendered HTML (not injected by JavaScript)
  • —Validate with OGProof to confirm Discordbot sees correct tags and the embed preview is accurate

Validate your OG tags now

Paste any URL and see exactly how it renders on Twitter, LinkedIn, Facebook, Discord, Slack, and iMessage — in seconds.

Try OGProof free →
← All articles