# The Ultimate Guide to Customizing Website Embeds in Discord
When someone drops a link to your website into Discord, Discord automatically fetches your page and transforms it into a rich visual card (a process known as **unfurling**).
Discord allows websites to render rich **Component Embeds**. You are no longer restricted to traditional title/description boxes—you can now build full **Components V2 layouts** with interactive-style link buttons, media galleries, separators, spoilers, and markdown directly from your website's HTML, **without needing a Discord bot or application!**
---
## Table of Contents
1. [How Discord Reads Your Website](#1-how-discord-reads-your-website)
2. [Method 1: The New Component Embeds](#2-method-1-the-new-component-embeds)
- [How It Works](#how-it-works)
- [Option A: Inline Script](#option-a-inline-script)
- [Option B: Linked JSON File](#option-b-linked-json-file)
- [Supported Components & Allowed Fields](#supported-components--allowed-fields)
- [Complete Component Embed Template](#complete-component-embed-template)
3. [Method 2: Standard Open Graph & Twitter Cards](#3-method-2-standard-open-graph--twitter-cards)
- [Quick Start OG Tags](#quick-start-og-tags)
- [Pro Tricks (Markdown, Accent Color, Galleries & Video)](#pro-tricks-markdown-accent-color-galleries--video)
4. [Testing, Caching & Debugging](#4-testing-caching--debugging)
5. [Troubleshooting Checklist](#5-troubleshooting-checklist)
---
## 1. How Discord Reads Your Website
When a link is posted:
1. Discord sends a `GET` request using the User-Agent:
```http
Mozilla/5.0 (compatible; Discordbot/2.0; +https://discordapp.com)
```
2. **Server-Side Rendered (SSR) only**: Discord **does not execute client-side JavaScript**. All meta tags and embed scripts must be present in the initial server response HTML.
3. **Speed & Timeout**: The entire fetch (page HTML + images/media metadata) must finish within **10 seconds**.
4. Always serve over **HTTPS** with a valid 2xx status code.
---
## 2. Method 1: The New Component Embeds
Component Embeds allow your website to render as a Discord **Components V2** container embed. This replaces the default preview card with custom Discord UI elements like link buttons, markdown headings, image galleries, and spoiler tags.
### Key Rules
- **Display-only & No Bot Required**: Buttons must be link buttons (`style: 5`) pointing to URLs. They do not trigger bot interaction events, meaning no bot token or server setup is required.
- **Root Element**: Must always be a `Container` (`type: 17`).
- **Capacity**: Up to 40 components per embed.
- **Always provide Open Graph fallbacks** in case Discord cannot display the component embed.
---
### Option A: Inline Script (Easiest)
Add a `
```
> **Note:** The `type` attribute must be strictly `application/json`. Do not wrap the JSON in variables or functions.
---
### Option B: Linked JSON File
If you prefer serving the JSON payload from an endpoint or static file, use ``:
```html
```
**Requirements for Linked JSON:**
- `href` must be an absolute `https://` URL.
- Must be **same-site** (the page's host, a subdomain, or its parent domain—e.g., `cdn.example.com` for `example.com`).
- Max file size: **3,000 bytes** raw response.
---
### Supported Components & Allowed Fields
| Type | Name | Description & Constraints |
|:---:|:---|:---|
| **17** | **Container** | The mandatory root wrapper. Supports `accent_color` (integer) and `spoiler` (boolean). |
| **1** | **Action Row** | Holds a horizontal row of buttons. |
| **2** | **Button** | Must use link style (`style: 5`). Allowed fields: `type`, `style`, `url`, `label`, `emoji`, `disabled`. **Forbidden**: `id`, `custom_id`, `sku_id` (will invalidate the payload). |
| **9** | **Section** | Contains child text components with an optional `accessory` (such as a thumbnail or button). |
| **10** | **Text Display** | Supports full Discord Markdown: headings (`#`), bold (`**`), italics (`*`), strikethrough, spoiler bars (`||`), code blocks, bullet points, and links. |
| **11** | **Thumbnail** | Image-only accessory for Sections. Uses `{ "url": "https://..." }`. Supports `spoiler: true`. |
| **12** | **Media Gallery** | Grid of images or playable videos (`items: [{ "media": { "url": "https://..." } }]`). |
| **14** | **Separator** | Visual horizontal divider. Can specify `"spacing": 1`. |
---
### Complete Component Embed Template
Here is a full copy-paste HTML example featuring a banner section, link button, media gallery, and text divider:
```html
CyberStrike v3.0 Announcement
CyberStrike v3.0 Launch
Neon City is now live for all players!
```
---
### Real-World Component Patterns & Templates
#### Pattern 1: GitHub Developer Profile Card
*Includes: Right-aligned avatar thumbnail accessory (`type: 11`), bio, formatted stats, clickable repository list, and a dual-button Action Row.*
```html
```
---
#### Pattern 2: Multi-Action Tool / Software Portal
*Includes: Red accent line, small uppercase eyebrow category, app logo thumbnail, multiple stacked action sections each with its own right-aligned button, and a subtext footer.*
```html
```
---
## 3. Method 2: Standard Open Graph & Twitter Cards
If you do not need buttons or custom component layouts, standard `` tags create clean, classic embed cards.
### Quick Start OG Tags
```html
```
### Pro Tricks
1. **Enable Markdown in Open Graph Descriptions:**
Set ``. When set to `rich`, Discord will parse markdown (e.g. `**bold**`, `*italics*`, `[links](...)`, and \`code\`) in `og:description`!
2. **Accent Colors (`theme-color`):**
Must be a 6 or 8 digit hex code (e.g., `#5865F2` or `#5865F2FF`). Shorthand like `#FFF` or CSS names like `red` are ignored by Discord.
3. **Multi-Image Gallery:**
Provide 2 to 4 `` tags. Discord automatically combines them into a 2x2 or grid gallery.
4. **Always Specify Image Dimensions:**
Include `og:image:width` and `og:image:height`. If Discord has to download and measure the image manually and the 10-second fetch budget expires, the image will be discarded.
5. **Inline Video Player:**
Point `` at a direct `.mp4`, `.webm`, or `.mov` file, set ``, and provide an `og:image` to serve as the poster frame.
---
## 4. Testing, Caching & Debugging
### Cache Invalidation Trick
Discord caches link previews for **~30 minutes**. If you update your meta tags or component payload, simply re-sharing the same URL will show the old cached embed.
- **Bypass Cache**: Append a dummy query parameter when sharing, e.g.:
`https://example.com/my-page?v=1`, `https://example.com/my-page?v=2`
- *Note*: Hash fragments (`#section`) do not bypass the cache.
### Official Embed Debugger
Discord provides an interactive inspection tool:
👉 [Discord Embed Debugger](https://discord.com/developers/embeds)
---
## 5. Troubleshooting Checklist
| Issue | Cause & Solution |
|:---|:---|
| **No embed appears at all** | • Your WAF or Cloudflare is blocking the `Discordbot` user agent. Whitelist `Mozilla/5.0 (compatible; Discordbot/2.0...)`. • The tags were rendered via client-side JavaScript. Ensure they are rendered on the server. • Exceeded character limits: `og:site_name` > 256 chars or URL > 2,048 chars will abort the entire embed. |
| **Image is missing** | • Image took too long to load (missing `og:image:width` and `og:image:height`). • Unsupported image format (Discord accepts PNG, JPEG, GIF, WebP, AVIF). • Image URL is relative without a leading `/`. |
| **Component embed ignored** | • Invalid component type or prohibited button property (buttons must be `style: 5` without `custom_id` or `id`). • Script `type` is not exactly `application/json`. • Root is not Container `type: 17`. |
| **Embed looks outdated** | • Discord cache hit. Reshare the link with `?v=newNumber`. |