Discord Interactive

Send Discord Components v2 interactive messages (buttons, selects, modals, rich layouts) via the message tool.

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

What you might expect	What OpenClaw actually uses
type: "container" wrapper	container: { accentColor: "..." } config object
type: "text_display"	type: "text" in blocks
type: "action_row" with nested components	type: "actions" with buttons or select
Manual custom_id on buttons	Auto-generated — just set label and style
accent_color: 0x3498db	accentColor: "#3498db" (hex string preferred)
type: "string_select"	select: { type: "string", ... } inside actions block

Block Types Summary

Block Type	Purpose	See
text	Markdown text	components.md
section	Text + optional thumbnail/button	components.md
separator	Divider line	components.md
actions	Buttons or select menu	components.md
media-gallery	Image gallery	components.md
file	File attachment	components.md

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