Tutorials

Getting Started

Let's create your first bot command. We'll make a simple greeting that responds when someone types !hello in your server.

1. Open Bot Commander and go to the Commands tab.
2. Tap the + button to create a new command.
3. Set the type to Message Received.
4. Set the command name to !hello.
5. In the channel message field, enter the response template shown below.
6. Save the command, host your bot, and type !hello in a Discord channel to test it.

Response Template

Hello $name! Welcome to $server.

Discord Output

Variables & Functions

Keywords let you insert dynamic information into your bot's responses. Variables like $name and $server are replaced with real values, and functions like $rollnum() and $random{} generate content on the fly.

1. Create a Message Received command named !info.
2. Enter the response template below in the channel message field.
3. Save, host your bot, and type !info to see the keywords in action.

Response Template

Hey $name! Today is $date.
Server: $server | Members: $memberCount
Your random number: $rollnum(1,100)
Fortune: $random{Good luck today!|Take it easy|Big things are coming}

Discord Output

Interaction Commands

Slash commands are Discord's modern way of interacting with bots. Users type / followed by the command name, and Discord shows autocomplete options. You can define typed parameters that Discord validates for you.

1. Go to the Interactions tab and tap + to create a new interaction command.
2. Set the command name to greet (no prefix needed for slash commands).
3. Set the description to Greet someone.
4. Add an option: type String, name person, description Who to greet.
5. Set the response template shown below.
6. Save, host your bot, and type /greet in Discord. Fill in the person option and send it.

Response Template

Hello $option(person)! $name says hi!

Discord Output

Buttons on Messages

You can add clickable buttons to your slash command responses. Each button can trigger its own response, assign roles, or show ephemeral messages that only the clicker can see.

1. Create a new interaction command named menu with the description Show the menu.
2. Set the response message to the template shown below.
3. Add a button with label Info, style Primary, and ID info_btn. Set its response to Here is some info about our server!
4. Add another button with label Help, style Secondary, and ID help_btn. Set its response to Need help? Ask in #support!
5. Optionally, check Ephemeral on the button responses so only the person who clicks sees the reply.
6. Save, host, and test with /menu in Discord.

Response Template

Welcome to the menu! Choose an option below.

Discord Output

If / Else Logic

Use $if, $elseif, $else, and $endif to make your bot respond differently based on conditions. You can check arguments, user properties, server info, and more.

1. Create a Message Received command named !role.
2. Enter the conditional template below in the channel message field.
3. Save and test. Try !role admin, !role mod, and !role anything to see the different responses.

Response Template

$if($args(0) == admin)
You are an admin, $namePlain!
$elseif($args(0) == mod)
You are a moderator, $namePlain.
$else
You are a regular member, $namePlain.
$endif

Discord Output

Alternate Output

Rich Embeds

Embeds are rich, formatted messages with a colored side bar, title, description, footer, images, and thumbnails. They make your bot's responses look polished and professional.

1. Create a Message Received command named !profile.
2. Enable the Send Embed option.
3. Fill in the embed fields as shown below. All fields are optional as long as you fill in at least one.
4. Save, host, and type !profile to see your embed.

Embed Fields

Title:       $namePlain's Profile
Description: Member of $server since the beginning!
Footer:      Requested on $date
Thumbnail:   $avatar

Discord Output

Member Join Events

You can make your bot automatically greet new members when they join your server. Combine this with role assignment to give new members a default role.

1. Create a new command and set the type to Member Join.
2. Enter the response template below in the channel message field.
3. Enable Assign/Remove Role and enter the role name (e.g. Member). This is case-sensitive.
4. Save and host. When someone joins your server, the bot will greet them and assign the role automatically.

Response Template

Welcome to $server, $name! You are member #$memberCount.
Please read the rules and enjoy your stay!

Discord Output

Saving Data Between Sessions

The botState object lets you store data that persists even when you stop and restart the bot. You can modify it inside $eval...$halt blocks and read its properties with $get(). You can also use $set() and $get() outside of eval blocks to store and retrieve values on the VM context directly.

1. Create a Message Received command named !count.
2. Enter the template below. The $eval block runs JavaScript and its return value replaces the block in the message. The botState object persists across bot restarts.
3. Save and test. The counter increments each time and survives bot restarts.

Response Template

$eval
if (!botState.count) botState.count = 0;
botState.count++;
return "This command has been used " + botState.count + " times!";
$halt

Discord Output

Managing Channels

Bot Commander includes functions for creating, deleting, and managing Discord channels directly from your command responses. Your bot needs the Manage Channels permission for these to work.

1. Create a Message Received command named !setup.
2. Enter the template below. It creates a new text channel and lists all channels in the server.
3. Save and test. Make sure your bot has the Manage Channels permission in your server.

Response Template

$createChannel(welcome, text)
Channel created! Your server now has $channelCount channels: $listChannels

Discord Output

Using AI in Commands

The $chat() function sends a prompt to AI and returns the response. Combine it with $messageAfterCommand to let users ask your bot anything. You'll need an API key configured in your bot settings.

1. Create a Message Received command named !ask.
2. Enter one of the response templates below. The simple version passes the user's question directly to AI. The advanced version adds formatting.
3. Save and test. Type !ask followed by any question.

Simple Template

$chat($messageAfterCommand)

Advanced Template

$name asked: $messageAfterCommand

AI Response: $chat($messageAfterCommand)

Discord Output

Command Only, Starts With & Phrase

When you create a "Message Received" command, you can choose how the bot matches incoming messages. By default the message must exactly match your command name. The Starts With and Phrase options change this behavior.

Command Only (Default)

The message must be exactly the command name, nothing more. For example, a command named !hello will only trigger when someone types exactly !hello. Typing !hello world or say !hello will not trigger it.

Command name: !hello
Triggers:     "!hello"        ✓
              "!hello world"  ✗
              "say !hello"    ✗

Starts With

Enable Starts With to trigger the command when a message begins with the command name. This is useful for commands that accept arguments. Use $args(0), $args(1), etc. to access the words after the command, or $messageAfterCommand to get everything after the command name.

Command name: !say
Starts With:  ✓
Triggers:     "!say hello"          ✓
              "!say how are you"    ✓
              "!say"                ✓
              "I say hello"         ✗

Phrase

Enable Phrase to trigger the command whenever the command name appears anywhere in a message. The match is case-insensitive. This is great for auto-responses to certain words or topics.

Command name: dog
Phrase:       ✓
Triggers:     "I love my dog"       ✓
              "DOG is the best"     ✓
              "hotdog"              ✓
              "I love my cat"       ✗

Kick, Ban & Voice Mute

Bot Commander has built-in moderation actions. When you enable kick, ban, or voice mute on a command, the bot performs that action on the mentioned user. The user running the command must have the matching Discord permission (Kick Members, Ban Members, or Mute Members). Usage is always: command @user.

Kick Command

Creates a command that kicks the mentioned user from the server.

1. Create a Message Received command named !kick.
2. Enable the Kick option in the moderation section.
3. Optionally add a channel message like the template below to confirm the action.
4. Save and test with !kick @user. Both you and the bot need the Kick Members permission.

$mentionedNamePlain has been kicked from the server.

Ban Command

Works the same way as kick, but permanently bans the user from the server.

1. Create a Message Received command named !ban.
2. Enable the Ban option in the moderation section.
3. Save and test with !ban @user. Both you and the bot need the Ban Members permission.

$mentionedNamePlain has been banned. Goodbye!

Voice Mute Command

Toggles server mute on a user in a voice channel. If they are unmuted, the bot mutes them. If they are already muted, it unmutes them.

1. Create a Message Received command named !mute.
2. Enable the Voice Mute option in the moderation section.
3. Save and test with !mute @user. You need the Mute Members permission and the target must be in a voice channel.

Assigning & Removing Roles

The Assign/Remove Role option toggles a role on the user who triggers the command. If they don't have the role, it's added. If they already have it, it's removed. This works with message commands, interaction buttons, and event-based commands like Member Join.

Toggle Role Command

A command that lets users give themselves (or remove) a role.

1. Create a Message Received command named !color-red.
2. Enable Assign/Remove Role and enter the role name or ID in the Role field (e.g. Red). This is case-sensitive.
3. Add a channel message to confirm the action.
4. Save and test. The bot needs the Manage Roles permission and its role must be higher than the role it's assigning.

$if($memberNickname == Red)
Removed the Red role from you, $namePlain.
$else
You now have the Red role, $namePlain!
$endif

Auto-Role on Join

You can also assign a role automatically when someone joins your server. Create a Member Join command with Assign/Remove Role enabled. Since a joining member never has the role yet, it will always be added. See the Welcome Messages tutorial for the full setup.

Role via Buttons

For a more modern approach, use an interaction command with buttons. Each button can assign a different role when clicked. Enable Assign/Remove Role on each button's action and set the corresponding role name. See the Interactive Buttons tutorial for how to set up buttons.

Adding & Responding to Reactions

There are two ways to use reactions in Bot Commander: making your bot add a reaction to a message as part of a command response, and creating commands that trigger when a user reacts to a message.

Bot Adds a Reaction

Any command can make the bot react to the triggering message. This is useful for acknowledgment or fun responses.

1. Create a Message Received command (e.g. !thumbs).
2. Enable the React option and enter the emoji name. For default emojis, use the emoji directly. For custom server emojis, use the emoji name without colons.
3. Save and test. The bot will add the reaction to the message that triggered the command.

Reaction Roles

A popular feature that lets users react to a specific message to gain or remove a role. This uses the Reaction Add command type.

1. Create a command and set the type to Reaction Add.
2. Set the command name to the emoji that will trigger the role. For default emojis use the emoji itself (e.g. ⭐). For custom emojis, use the name without colons.
3. Enable Require Specific Message and paste the message ID of the message users will react to. To get a message ID, enable Developer Mode in Discord settings, then right-click the message and select Copy Message ID.
4. Enable Assign/Remove Role and enter the role name (e.g. Announcements).
5. Save and host. React to the message with the emoji to gain the role, react again to remove it.
6. Repeat for each role you want to assign. Create one command per emoji/role combination.

Example setup for a role selection message:

⭐ → Announcements role
🎮 → Gamer role
🎨 → Artist role

Each emoji gets its own Reaction Add command
with the matching role name.

JavaScript Eval Blocks

For advanced logic beyond what keywords and conditionals offer, you can run JavaScript code inside your responses using $eval...$halt blocks. The code runs like an async function in a sandboxed environment with access to Math, Date, and the persistent botState object. The return value of the block replaces it in the message.

How It Works

The code between $eval and $halt is wrapped in a function and executed. Any BCFD keywords inside the block (like $name or $messageAfterCommand) are resolved before the JavaScript runs, so you can use them as values in your code. Use return to output a result — the returned value replaces the entire $eval...$halt block in the message.

Important: Variables declared with var or let inside the block are local to that function and cannot be accessed with $get() outside it. To share data between eval blocks or with the rest of the message, use botState (which persists across commands and restarts) or $set()/$get() which store values on the VM context directly.

Basic Example

A simple greeting command that uses JavaScript to build a response.

1. Create a Message Received command named !greetme.
2. Enter the template below. The return value replaces the eval block.
3. Save and test.

$eval
var hour = new Date().getHours();
if (hour < 12) {
  return "Good morning, $namePlain!";
} else if (hour < 18) {
  return "Good afternoon, $namePlain!";
} else {
  return "Good evening, $namePlain!";
}
$halt

Mixing Eval with Regular Text

The eval block is just one part of your message. You can put regular text and keywords before and after it. The return value gets inserted where the block was.

Hello $name! $eval
var num = Math.floor(Math.random() * 100) + 1;
return "Your lucky number is " + num + ".";
$halt Have a great day!

Advanced: Using botState

The botState object is available inside eval blocks and persists across commands and bot restarts. Use it to track per-user data, counters, or any state your bot needs to remember.

$eval
if (!botState.users) botState.users = {};
var id = "$id";
if (!botState.users[id]) botState.users[id] = 0;
botState.users[id]++;
var uses = botState.users[id];
if (uses === 1) {
  return "Welcome, $namePlain! This is your first time using this command.";
} else {
  return "Welcome back, $namePlain! You've used this command " + uses + " times.";
}
$halt