What are Components V2?

Components V2 is Discord’s modern system for building messages. Instead of writing some text and attaching an embed, you build the message piece by piece, like a page: text, images, separators, buttons and menus, in any order you like.

Preview

My BotAPPToday at 12:00 PM

Hi 👋

This message is made only with components.

👍Like

payload.json

{
  "flags": 32768,
  "components": [
    {
      "type": 10,
      "content": "# Hi 👋\nThis message is made **only with components**."
    },
    {
      "type": 1,
      "components": [
        {
          "type": 2,
          "style": 3,
          "label": "Like",
          "custom_id": "like",
          "emoji": {
            "name": "👍"
          }
        }
      ]
    }
  ]
}

The idea in one sentence

A V2 message is a list of components. Some components show things (text, images), some group things (containers, sections) and some react to clicks (buttons, menus).

The three kinds of components

Layout

Organize other components: Container, Section, Action Row, Separator and, in modals, Label.

Content

Display information: Text Display, Thumbnail, Media Gallery and File.

Interactive

Users can use them: Button, the Select Menus, Text Input, File Upload, Radio Group and Checkbox.

The IS_COMPONENTS_V2 flag

For Discord to treat your message as V2, send the IS_COMPONENTS_V2 flag in the message’s flags field.

Name	Value	Calculation
IS_COMPONENTS_V2	32768	1 << 15

If you also want the message to be ephemeral (only the person who used the command sees it), add the EPHEMERAL flag (64): 32768 + 64 = 32832.

The flag changes the rules

• You can’t use content, embeds, poll or stickers anymore. Text goes inside Text Display components.
• Attachments are not shown on their own: display them with a File, Thumbnail or Media Gallery.
• A message can have at most 40 components in total (including nested ones).
• It can’t be removed: if you edit a V2 message, it stays V2.

V2 vs. embeds and legacy components

	Embeds + legacy components	Components V2
Message text	content	Text Display component
Colored card	embeds	Container with accent_color
Images	One big image and one thumbnail per embed	Media Gallery with up to 10 images, thumbnails in any section
Buttons	Only at the bottom (up to 5 rows)	Anywhere: inside containers or next to text
Order	Fixed	Free: you decide
Max components	5 action rows	40 components in total

What is the id field?

Every component has two common fields:

Field	Type	Description
type	integer	required The component type (for example 10 = Text Display).
id	32-bit integer	optional Unique identifier within the message. If you omit it, Discord assigns one automatically in order. 0 is treated as empty.

Don't confuse id with custom_id

• id identifies a component inside the message (for example, to know which one to edit).
• custom_id is what your bot receives when someone clicks a button or uses a menu. Only interactive components have it.

Where can I use them?

Components V2 work anywhere you send a message:

• Create message in a channel (POST /channels/{channel.id}/messages).
• Responding to an interaction (commands, buttons, menus, modals).
• Follow-up messages and editing the original response.
• Webhooks, adding ?with_components=true to the URL.

Next step

You know the basics. Now let’s send your first message.