Skip to content
Bot Creator
Download
Blocks

Blocks — Visual No-Code Programming Reference

The Blocks system is Bot Creator’s visual programming engine. Inspired by modular snap-together card environments (like Scratch), it enables creators on iOS, Android, and Desktop to build complete Discord bots without writing a single line of raw code.

Blocks run directly on the native Dart engine. Each block compiles into a structured, typed, deterministic Action with inputs, outputs, and a unified error lifecycle handler.

1. Block Anatomy

In the mobile app, blocks are represented as rounded cards stacked vertically, connected by flow lines:

SEND A MESSAGE Key: my_message
Target channel string
((channel.id))
Message text content string
Hello ((user.username))! Welcome to ((guild.name)).
Automatically pin message
+
RESPOND TO INTERACTION Terminal
Text content
Message sent to the channel!
Ephemeral Reply (visible only to you)

Underlying JSON Structure

Each block corresponds to an Action object serialized in the bot:

{
  "type": "respondWithMessage",
  "key": "welcome_reply",
  "enabled": true,
  "depend_on": [],
  "error": {
    "mode": "stop",
    "jumpToActionId": null,
    "skipCount": 0
  },
  "payload": {
    "content": "Hello ((user.username))! Welcome to ((guild.name)).",
    "ephemeral": true
  }
}

Field Definitions

Field Type Description
type String Exact block identifier corresponding to BotCreatorActionType (e.g. sendMessage, createChannel, ifBlock).
payload Object Dictionary of block parameters (IDs, text, booleans, embeds, options).
key String Optional unique identifier assigned to the block output for subsequent references (((action.key))).
enabled Boolean Default: true. If false, the engine skips the action without raising an error.
depend_on Array<String> Keys of prerequisite actions that must execute before this block runs.
error Object Error handling behavior: mode (stop, continue, jump, skip).

2. Inputs, Outputs, and Context Variables

Discord Context Variables ((...))

Input fields accept dynamic placeholders resolved at runtime:

  • User: ((user.id)), ((user.username)), ((user.avatar))
  • Guild / Server: ((guild.id)), ((guild.name)), ((guild.memberCount))
  • Channel: ((channel.id)), ((channel.name))
  • Slash Options: ((opts.option_name)) (or ((opts.option_name.id)) for IDs)
  • Components: ((interaction.customId)), ((interaction.userId))

Block Outputs ((action.<key>))

When a block produces an identifier or result (for example createChannel creates a channel and returns its Snowflake ID, or httpRequest returns a JSON object), assign it a Key in the editor (e.g. ticket_chan). Subsequent blocks access it via:

((action.ticket_chan))

3. Step-by-Step Beginner Guide: 3 Core Projects

Each project includes an interactive dual view: see how it connects in the mobile app or read the equivalent script code, along with a simulated Discord visual preview!

Project 1: The /ping Slash Command

Goal: Build a slash command that replies with the bot’s latency in a clean embed.

SLASH COMMAND: /ping Trigger
Command name: /ping • Description: Measures bot latency.
RESPOND TO INTERACTION Terminal
Embed Title
🏓 Pong!
Embed Description
WebSocket API Latency: ((bot.ping))ms
Embed Color
#5865F2 (Blurple)
Ephemeral Reply 
;; Native slash command reply (no $sendMessage needed)
$title[🏓 Pong!]
$description[WebSocket API Latency: **$ping ms**]
$color[#5865F2]

Realistic Discord Preview

🤖
Bot Creator Assistant BOT ✔ Today at 3:00 PM
🏓 Pong!
WebSocket API Latency: 24 ms

Project 2: Automatic Welcome Message

Goal: When a new member joins the server, send a personalized welcome message to the #welcome channel.

EVENT: guildMemberAdd Event
Triggered automatically whenever a user joins the Discord server.
SEND A MESSAGE Action
Target channel (#welcome channel ID)
112233445566778899
Text content
Welcome <@((user.id))> to **((guild.name))**! 🎉 We are now ((guild.memberCount)) members!
;; Triggered on guildMemberAdd event
$useChannel[112233445566778899]
Welcome <@$authorID> to **$serverName**! 🎉
We are now $membersCount members!

Realistic Discord Preview

🤖
Bot Creator Assistant BOT ✔ Today at 3:05 PM
Welcome @Jeremy to Bot Creator Community! 🎉 We are now 1,420 members!

Project 3: Interactive Role Assignment via Button

Goal: Deploy a verification panel with an interactive button. When clicked, the user receives a role without public chat clutter.

BUTTON CLICK: verify_member Trigger
Triggered when the button with customId verify_member is pressed.
ADD A ROLE Moderation
Target user
((user.id))
Role identifier (Member Role ID)
998877665544332211
RESPOND TO INTERACTION Terminal
Text content
✅ Congratulations ((user.username))! You have been given the Member role.
Ephemeral Reply 
;; Button click event on verify_member
$giveRole[$authorID;998877665544332211]
$ephemeral
✅ Congratulations $username! You have been given the Member role.

Realistic Discord Preview

🤖
Bot Creator Assistant BOT ✔ Today at 3:10 PM
✅ Congratulations Jeremy! You have been given the Member role.
Only you can see this • Dismiss message

4. Explore All Blocks

To browse all 112 blocks available in the mobile app with their fields, default values, and script equivalents: