Flow anatomy
Everything a Builder bot does is a flow. This page covers every part of one: the trigger that starts it, the options it accepts, the steps it runs, and the gates that control who can use it.
The trigger: when does it run
Every flow starts with exactly one trigger. The trigger type decides what makes the flow run - a slash command, a chat keyword, a member joining, a schedule, a button click. The full list with per-trigger variables is on the trigger reference. The most common one is Command: the flow's name becomes a slash command, and it also answers to the bot's prefix (!name) so both power users and clickers are covered.
Flow names for commands must be lowercase letters, numbers, underscores, and hyphens - Discord's slash-command rules. Event flows can keep display names since users never type them.
Slash options: real inputs, not one text box
Commands take input through typed slash options, declared in the flow's settings panel. Each option shows up in Discord as a proper picker - a user picker, a channel dropdown, a role selector, an attachment upload, a number field, a yes/no toggle, or a text field with choices.
| Option type | {option:name} gives | {optionId:name} gives |
|---|---|---|
| user | A mention (<@id>) | The raw user ID |
| channel | A channel link (<#id>) | The raw channel ID |
| role | A role mention (<@&id>) | The raw role ID |
| mentionable | User or role mention | The raw ID |
| attachment | The file URL | The attachment ID |
| string / integer / number / boolean | The typed value | The same value |
Use {option:name} in text you show to people, and {optionId:name} in any field that wants an ID (target user ID, channel ID, role ID). Options can be required or optional, take up to 25 choices, and string/number options accept min/max bounds enforced by Discord before your flow even runs.
The args box, explained
Older flows use {args} and {arg:0} - a single free-text field. These still work, but the args box now only registers on commands that actually reference them, so clean typed-option commands get a clean Discord UI. The Free-text args input setting on the flow controls this: Auto (default) detects usage, Always forces it on, Never suppresses it. The settings panel shows you which inputs the flow actually references.
Prefix commands are different: {args} always holds the full message text after the command name and {arg:N} the Nth word - that is the correct primitive there and needs no options.
The canvas: wiring steps together
- Entry node: the step wired directly to the trigger runs first. From there, each step's output points to the next.
- Branches: Condition, If Variable, Random Branch, AI Condition, Ask Question, and Show Modal have
thenandelseoutputs. Wire both - an unwired branch produces a canvas warning, and the false path just does nothing. - Switch Case: N-way branch on a variable's value - each case gets its own output wire, the bottom output is the default.
- Loops: For Each runs its body wire once per item in a list variable (members, roles, channels, JSON arrays) with
{var:item}and{var:itemIndex}available inside. Loop While and Loop Until repeat on a condition. Hard caps: 100 iterations, 3 levels of nesting. - Wait and Wait For Event: pause the flow mid-run. Wait accepts up to 300 seconds; for longer delays use the Reminder node, which persists across restarts.
- Error wire: every node has an amber output on its bottom edge. If the step fails (bad permission, API error, missing config), execution follows that wire instead of the normal path - route it to a log channel or a fallback reply. Unwired, the run continues past the failure.
{var:error}holds the error text. - Loops back to earlier nodes: legal, but flagged as warnings at save time and capped at 300 steps per run - wire carefully.
- Disabled steps: toggling a step off bypasses it at runtime - useful for temporarily disabling a branch without deleting it.
Who can run it: gates and limits
The flow settings control access. These apply on every trigger type - slash, prefix, keyword, and events.
| Setting | What it does |
|---|---|
| Allowed roles | Only members with one of these role IDs can run it. Blank = everyone. The server owner and the bot's owner bypass this so they can never lock themselves out; nobody else does. |
| Allowed channels | Only runs in these channel IDs. Blank = anywhere. |
| Cooldown | Per-user cooldown in seconds between runs of this flow. |
| Daily limit | Per-user daily run cap. 0 = unlimited. |
| Server owner only | Only the guild owner can run it, regardless of roles. |
| NSFW | Only runs in age-restricted channels. |
| Aliases | Extra prefix names for the same command (!lb for /leaderboard). |
| Enabled | Turn the flow off without deleting it - it stays registered but cannot run. |
| Folder | Organizes flows in the list. No runtime effect. |
For finer-grained checks inside the flow, the Condition step branches on roles, permissions, channel, booster status, or a specific user ID - that is how you build "only Houseguests see this path" logic rather than all-or-nothing gating.
Subcommands and groups
Setting a Parent command on a flow turns it into a subcommand: admin + ban registers as /admin ban. A Group name adds one more level: /admin mod ban. The parent command itself never runs alone - it is just the umbrella. This keeps big bots tidy: /economy balance, /economy daily, /economy top.
Testing before you ship
- Simulate: runs the in-editor graph - unsaved changes included - against a mock context and traces what every step would do: messages, variables, data changes, the branch path taken. Nothing touches Discord.
- Replay: re-runs the flow's last real execution through the simulator with the same inputs it actually started with - the fastest way to debug "it worked yesterday."
- AI explain / fix: paid-plan tools that send the draft to the platform AI for a plain-language walkthrough or a diagnosis with suggested repairs.
- Logs: the bot's Logs tab shows every real run's warnings and errors - permission failures, missing configs, rate caps - the first place to look when a command does nothing.
Templates
Two dozen template packs install complete multi-flow systems in one click: welcome + autorole, reaction roles, leveling, counting, starboard, confessions, AFK, invite rewards, server logs, moderation, tickets, music, Minecraft, FiveM, and more. They are real flows you can study and edit - the fastest way to learn the node conventions is to apply one and read it.