Discord Interactive Components (Components v2)

Send rich, interactive messages in Discord using the message tool's components parameter. This replaces plain text with buttons, select menus, modals, and structured layouts.

When to Use Components v2

ALWAYS prefer components over plain text when:

• You need user confirmation → buttons (Yes/No, Approve/Reject)
• You need user selection → select menus (agents, priorities, options)
• You want structured information display → text blocks + sections + separators
• You want to collect form data → modals with text inputs, selects, checkboxes
• You want visual distinction → accent-colored containers

Use plain text when:

• Simple conversational response, no actions needed
• Quick one-liner answer

Quick Reference

The components parameter is an object with this structure:

{
  // Top-level fields
  text: "Optional top-level text (rendered as first TextDisplay)",
  reusable: true,  // Keep buttons/selects active for multiple clicks (default: single-use)
  container: {
    accentColor: "#3498db",  // Left border color (hex string or number)
    spoiler: false
  },
  // Content blocks (rendered in order inside the container)
  blocks: [
    { type: "text", text: "Markdown text block" },
    { type: "section", text: "Main text", accessory: { type: "thumbnail", url: "https://..." } },
    { type: "separator", spacing: "small", divider: true },
    { type: "actions", buttons: [{ label: "Click me", style: "success" }] },
    { type: "actions", select: { type: "string", placeholder: "Choose...", options: [...] } },
    { type: "media-gallery", items: [{ url: "https://...", description: "..." }] },
    { type: "file", file: "attachment://report.pdf" }
  ],
  // Optional modal form (auto-generates a trigger button)
  modal: {
    title: "Form Title",
    triggerLabel: "Open Form",
    fields: [{ type: "text", label: "Your name" }]
  }
}

Quick Start — Confirmation

// message tool call
{
  action: "send",
  channel: "discord",
  target: "channel:CHANNEL_ID",
  components: {
    text: "**Confirm action?**",
    reusable: false,
    container: { accentColor: "#3498db" },
    blocks: [
      {
        type: "actions",
        buttons: [
          { label: "Yes", style: "success" },
          { label: "No", style: "secondary" }
        ]
      }
    ]
  }
}

No custom_id needed — OpenClaw generates unique IDs automatically. When the user clicks, you receive a message like Clicked "Yes".

Key Differences from Raw Discord API

Block Types Summary

Handling Interactions

When a user clicks a button or selects an option, OpenClaw delivers it as a normal inbound message:

• Button click → Clicked "Yes".
• Select → Selected option_a from "Pick an option".

No special callback handling needed — just read the incoming message text. See handling.md for patterns.

Important Rules

• No custom_id — OpenClaw auto-generates unique IDs for all interactive elements
• No embeds — Components v2 and embeds cannot coexist in the same message
• reusable: true — Set this to allow buttons/selects to be clicked multiple times
• allowedUsers — Optionally restrict who can click a button (array of Discord user IDs)
• Actions block — Must have EITHER buttons OR select, never both
• Max 5 buttons per actions block, max 1 select per actions block

Examples

See references/examples.md for complete scenarios:

• Yes/No confirmation
• Agent/option selection
• Status card with actions
• Modal form collection
• Multi-step workflow