Skip to main content
Message components are a powerful way to add interactivity to your messages. They allow you to create rich, interactive experiences for your users, making it easier for them to engage with your content.
If you are sending components as part of a webhook, you’ll need to use the ?with_components=true query param, otherwise they’ll be ignored.

​
Prerequisites

  • You must have a Discord account and be a member of the Discord Developer Portal.
  • You must have a Discord application created in the Discord Developer Portal.
  • You must have the necessary permissions to send messages in the channel where you want to use components.

​
Sending a Message with a Component

To send a message with a component, set the IS_COMPONENTS_V2 flag (1<<15, value 32768) in your message’s flags field. This can be done when using Message Create, Execute Webhook, or responding to an interaction.
Setting the IS_COMPONENTS_V2 message flag cannot be reverted: once a message has been sent, the flag cannot be removed when editing.
This flag indicates that the message contains components and disables traditional content and embeds. All content must be sent as components. 
{
  "flags": 32768,
  "components": [
    {
      "type": 10,
      "content": "This is a message using the Text Display component"
    }
  ]
}

​
Sending a Message with Multiple Components

Include multiple component objects in the components array to send multiple components in a single message: 
{
  "flags": 32768,
  "components": [
    {
      "type": 10,
      "content": "This is a Text Display component."
    },
    {
      "type": 10,
      "content": "This is another Text Display component!"
    }
  ]
}

​
Nesting Components with Layout Components

You can nest components within layout components to control how information, images, and interactive elements are displayed. See the component types reference for a complete list of available layout components. For example, you can create a message with an Action Row component containing multiple Button components: 
{
  "flags": 32768,
  "components": [
    {
      "type": 10,
      "content": "This is a message with v2 components"
    },
    {
      "type": 1,
      "components": [
        {
          "type": 2,
          "style": 1,
          "label": "Click Me",
          "custom_id": "click_me_1"
        },
        {
          "type": 2,
          "style": 2,
          "label": "Click Me Too",
          "custom_id": "click_me_2"
        }
      ]
    }
  ]
}

​
Common Patterns

Display a text message alongside action buttons using a Text Display and an Action Row:
{
  "flags": 32768,
  "components": [
    {
      "type": 10,
      "content": "Would you like to proceed?"
    },
    {
      "type": 1,
      "components": [
        {
          "type": 2,
          "style": 3,
          "label": "Confirm",
          "custom_id": "confirm_action"
        },
        {
          "type": 2,
          "style": 4,
          "label": "Cancel",
          "custom_id": "cancel_action"
        }
      ]
    }
  ]
}

​
Using Message Components with Interactions

When a user interacts with an interactive message component, your app will receive an interaction event. This event contains:
  • The type of interaction (MESSAGE_COMPONENT, which is type 3)
  • The custom_id of the component that was interacted with
  • For select menus, the values the user selected
  • Metadata about the context (guild, channel, user, etc.)
See the component types reference for a list of interactive message components and their interaction event payload structures. You can use this information to:
  • Respond with a new message
  • Update the original message (using UPDATE_MESSAGE callback type 7)
  • Open a modal to collect more information
  • Perform backend operations and defer the response
Use DEFERRED_UPDATE_MESSAGE (callback type 6) when your bot needs time to process the interaction. This acknowledges the interaction without showing a loading state to the user, and lets you edit the original message later.
Check out the Interactions documentation for more information on handling interactions and responding to user input from interactive components.

​
Legacy Component Behavior

Before the IS_COMPONENTS_V2 flag was introduced, message components were sent alongside message content. Legacy behavior allows a subset of components (Action Rows, buttons, and select menus) without the flag, and the message content and embeds fields still work normally. Apps using legacy behavior will continue to work, but we recommend using the IS_COMPONENTS_V2 flag for new apps and features.
Legacy messages allow up to 5 Action Rows as top-level components.
{
  "content": "This is a message with legacy components",
  "components": [
    {
      "type": 1,
      "components": [
        {
          "type": 2,
          "style": 1,
          "label": "Click Me",
          "custom_id": "click_me_1"
        }
      ]
    }
  ]
}