Interactions

What interactions are

Interactions are Discord slash commands. A user types /, chooses your command, fills in any options, and Discord sends the interaction to Bot Commander. The bot must be hosted for the command and its buttons to respond.

For a guided example, see the Slash Commands and Interactive Buttons tutorials.

Create and publish an interaction

  1. Open the Interactions tab and create a new interaction.
  2. Enter its command name, description, options, and root response action.
  3. Save the interaction and host the bot.
  4. Register the interaction, or use Sync All to make Discord match the app's interaction list.
  5. Run the slash command in Discord and verify its response.

Registration and propagation

The bot must be connected before an interaction can be registered, unregistered, or synced. Global interactions can take up to an hour to appear in Discord. A guild interaction uses guildId to register in one server and normally appears immediately.

Changing commandName, commandDescription, or options changes Discord's command definition and requires registration again. Response actions, buttons, and cooldown behavior run locally and can be changed without re-registering the Discord command.

Sync All replaces the bot's registered global commands with the current interaction list, so removed interactions are also removed from Discord. The app manages isRegistered; it is a local status indicator, not confirmation from Discord on every launch.

Name and description

commandName is the text users type after /. It must be 1-32 characters and follow Discord's slash-command naming rules; lowercase letters, numbers, hyphens, and underscores are the safest choices. Do not include the slash. commandDescription is required and must be 1-100 characters.

Command options

options are typed inputs Discord collects before running the command. Each option has a unique name, a description, a numeric type, and a required setting. Required options must be completed before Discord will submit the command.

Supported option types are 3 String, 4 Integer, 5 Boolean, 6 User, 7 Channel, 8 Role, and 10 Number. The optional choices array can restrict String, Integer, or Number options to named values when using JSON or agent editing.

Using option values

Use $option(name) in any interaction response template, replacing name with the exact option name. User, Channel, and Role options produce the selected Discord ID, while other option types produce their submitted value. 

Hello $option(person)! Your topic is $option(topic).

Messages and embeds

The root action can send a channel message, channel embed, private message, private embed, or any useful combination. Channel responses become the Discord interaction reply. Private responses are sent separately by direct message and can fail if the user blocks DMs.

Embed templates support a title, description, hex color, image URL, thumbnail URL, and footer. At least one visible embed field must be filled in. Interaction templates support the same BCFD keywords and functions as other commands when the required user, server, or channel context is available.

Ephemeral and deferred replies

ephemeral makes the channel response visible only to the person who ran the command or clicked the button. It does not change separate direct messages.

deferReply acknowledges the interaction before longer template or Discord work finishes, avoiding Discord's short initial response deadline. The completed response keeps the configured ephemeral setting.

Assign or remove a role

isRoleAssigner toggles roleToAssign on the member who ran the command or clicked the button. The bot needs Manage Roles, and its highest role must be above the target role. This action only works in a server.

Moderation actions

isKick, isBan, and isVoiceMute target the User option named by targetUserOptionName. The caller and bot need the matching Discord permission. deleteX and deleteNum bulk-delete up to 100 messages and require Manage Messages in a text channel.

Moderation and bulk deletion are supported only on the interaction's root action. Button actions can send responses, send DMs, toggle roles, and show more buttons.

Button fields and styles

Each button has a label, numeric style, optional emoji, disabled state, and either a customId with an action or a link url. Styles are 1 Primary, 2 Secondary, 3 Success, 4 Danger, and 5 Link.

Every non-link button needs a unique customId so Bot Commander can find its action. Link buttons require a valid URL, open that URL directly, and do not run a Bot Commander action.

Button actions and nesting

A non-link button has its own reusable interaction action. It can reply with text or an embed, send a DM, toggle a role, and include another set of buttons. Ephemeral and deferred reply settings apply separately to each button action.

Each response supports up to five buttons in one row. The editor allows three levels of nested button responses. Keep button labels and response paths short so users can understand where each click leads.

Inactive and outdated buttons

Buttons work only while the bot is hosted and the interaction still contains their custom IDs. If a button on an older Discord message can no longer be found, Bot Commander replies that the button is no longer active. Disabled buttons remain visible but cannot be clicked.

Cooldown settings

cooldown is the duration in seconds. Zero or an omitted value disables it. cooldownType can be User, Server, or Global to track usage per person, per server, or across every server.

cooldownMessage is an optional BCFD template returned ephemerally when a user is blocked. Use $cooldownRemaining() to include the remaining seconds. Without a custom message, Bot Commander sends its standard remaining-time response.

The cooldown applies when the slash command runs and is recorded after its root action succeeds. Button clicks do not start or check the command cooldown.

Interaction resource fields

commandName, commandDescription, and options define the Discord slash command. rootAction defines its local response. guildId optionally limits registration to one server. cooldown, cooldownType, and cooldownMessage control rate limits.

id is assigned by the app and identifies the local resource. isRegistered is managed by the app. Preserve both fields when editing an existing interaction; new interactions should let the app assign them.

Interaction action fields

Response toggles and templates are sendChannelMessage, channelMessage, sendPrivateMessage, privateMessage, sendChannelEmbed, channelEmbed, sendPrivateEmbed, and privateEmbed.

Other fields are isRoleAssigner, roleToAssign, isKick, isBan, isVoiceMute, targetUserOptionName, deleteX, deleteNum, ephemeral, deferReply, and buttons.

Interaction button fields

Button resources contain customId, label, style, optional emoji, optional url, disabled, and a nested action. Button actions use the same action shape recursively.

Canonical interaction JSON example 

{
  "id": "app-assigned",
  "commandName": "greet",
  "commandDescription": "Greet a member",
  "options": [
    { "name": "person", "description": "Who to greet", "type": 6, "required": true }
  ],
  "rootAction": {
    "sendChannelMessage": true,
    "channelMessage": "Hello $option(person)!",
    "sendPrivateMessage": false,
    "privateMessage": "",
    "sendChannelEmbed": false,
    "channelEmbed": { "title": "", "description": "", "hexColor": "", "imageURL": "", "thumbnailURL": "", "footer": "" },
    "sendPrivateEmbed": false,
    "privateEmbed": { "title": "", "description": "", "hexColor": "", "imageURL": "", "thumbnailURL": "", "footer": "" },
    "isRoleAssigner": false,
    "roleToAssign": "",
    "isKick": false,
    "isBan": false,
    "isVoiceMute": false,
    "targetUserOptionName": "",
    "deleteX": false,
    "deleteNum": 0,
    "ephemeral": false,
    "deferReply": false,
    "buttons": []
  },
  "isRegistered": false,
  "cooldown": 0,
  "cooldownType": "",
  "cooldownMessage": ""
}

Omit guildId for global registration or set it to one server ID for guild registration. Choices and nested buttons can be added to the corresponding arrays.