Discord Components V2: Complete Guide

What changed in Components V2

Legacy webhook messages split presentation between top-level content and embeds. Components V2 moves the visible message into one components array and adds layout primitives such as Container and Section. Once the IS_COMPONENTS_V2 message flag is set, top-level content and embeds are disabled; text belongs in Text Display components instead.

The result is more composable than a legacy embed. A Container can hold formatted text, separators, media galleries, files and action rows behind one accent colour. A Section can place one to three text blocks beside a thumbnail or button accessory. You can mix several top-level blocks rather than forcing the whole design into one card.

Message component type IDs and placement

A minimal Components V2 webhook payload

This payload creates a coloured container with a heading, supporting text, a separator and a link button. The numeric flag is 32768, or 1 << 15. DWEEB adds the V2 flag when it serializes and sends a visual design.

{
  "flags": 32768,
  "components": [
    {
      "type": 17,
      "accent_color": 5793266,
      "components": [
        { "type": 10, "content": "# Server update\nEverything you need in one place." },
        { "type": 14, "divider": true, "spacing": 1 },
        {
          "type": 1,
          "components": [
            { "type": 2, "style": 5, "label": "Read the guide", "url": "https://example.com/update" }
          ]
        }
      ]
    }
  ]
}

Current message and nesting limits

DWEEB validates against the same limits before send, so the live issue list is also a practical limits calculator. Discord can change its API over time; the numbers below are generated from the constants used by the editor rather than copied into a second, drifting list.

• 40 components total, including nested components
• 10 top-level components
• 4,000 characters across text-bearing component fields
• 39 children in a Container when it is the only top-level component
• 1–3 Text Display children in a Section
• 10 Media Gallery items, 5 buttons per Action Row and 25 string-select options

Webhooks, buttons and app ownership

A person-created incoming webhook can post non-interactive Components V2 when the request opts into components. Link buttons are safe because Discord opens a URL and no application has to receive a click. Buttons with custom IDs and select menus are different: an application must own the webhook and acknowledge the interaction.

That distinction explains the setup badges in DWEEB. Static layouts work with any incoming webhook. DWEEB-hosted replies use a guided app-owned destination. Features that change roles, create channels or perform other privileged actions also require the relevant Discord app installation.

Sending the payload from a bot or your own code

The same components array works wherever the message is sent from, so a design checked visually does not have to be rebuilt in code. Only the transport and the flag handling differ.

• Export from the visual builder once the preview looks right, then paste the payload into your project
• Import a payload your code already sends to adjust it visually instead of editing braces
• Keep the numeric component types as the source of truth; builder classes in any library are wrappers over them

A reliable build workflow

The editable Components V2 showcase contains every major block and is a faster reference than assembling the numeric types by hand. Open it, select a component, and compare the visual tree with exported JSON.

If the API rejects a payload or drops a component, use the webhook error guide to separate layout validation from delivery and app-ownership problems. For notification behavior, see webhook mentions and allowed_mentions.

• Start with information hierarchy: one purpose, one first action and only then decoration.
• Use Containers for visual grouping, not as a wrapper around every isolated line.
• Prefer a Section when a thumbnail or single button belongs directly to a short block of text.
• Validate character, nesting and interaction ownership before you copy or send JSON.
• Test the final post in a real channel; a preview cannot reproduce every client width or permission failure.