API reference
Checks
Cooldowns, permission checks, role and channel rules, and custom error messages.
A check stops the command when a rule is not met. The person sees an error message, and nothing else runs.
Put checks at the top of the pre-hook, before any work.
These functions work in slash commands, text commands and component handlers. You do not need to write await in front of them.
Tip
You do not need if around a check. Each one stops the command by itself, with a good message.
cooldown#
Makes a member wait before using the command again.
cooldown(time, key=None, error_message=None, count=1)| Argument | What it does |
|---|---|
time | How long to wait, in words: "30 seconds", "1 hour", "1 day". |
key | Who shares the cooldown. Default is the member who ran it. |
error_message | Your own message. It can use the placeholders below. |
count | How many uses are allowed before the wait starts. |
cooldown("1 day", error_message="You already claimed today. Come back %relative%.")
coins = int(member_var("coins", 0)) + 100
update_member_var("coins", coins)
set_content(f"You got 100 coins! You now have {coins}.")Placeholders for error_message:
| Placeholder | Becomes | Shows in Discord as |
|---|---|---|
%time% | 5 minutes | plain text |
%relative% | a Discord time tag | in 5 minutes, counting down by itself |
%at% | a Discord time tag | 9:46 PM, in each reader's time zone |
%timestamp% | 1788731206 | the raw number of seconds |
Use %time% for "try again after %time%". Use %relative% for "try again %relative%".
Who shares the cooldown
key | Effect |
|---|---|
| not set | Each member has their own cooldown. |
server.id | One cooldown for the whole server. |
channel.id | One cooldown per channel. |
[user.id, channel.id] | One per member, per channel. |
In a component handler
In a component handler, cooldown(time, key=None) does not stop the script. It returns False when the click may go on, or the time left as text when it must wait.
left = cooldown("10 seconds")
if left:
set_error(f"Slow down. Try again in {left}.")require_permission#
Lets the command run only for members with all these Discord permissions. Administrators always pass.
require_permission(*permissions, error_message=None)require_permission("ban_members")Write permission names in lowercase with _. Common ones:
administrator, manage_server, manage_roles, manage_channels, manage_messages, kick_members, ban_members, timeout_members, mention_roles, send_messages, view_channel.
A wrong name stops the script and lists every valid name.
allowed_roles#
Lets the command run only for members with at least one of these roles.
allowed_roles(*roles, error_message=None)allowed_roles("Staff", "Moderator", error_message="Only staff can use this.")Roles can be role objects, role IDs or exact role names.
banned_roles#
Stops members with any of these roles from running the command.
banned_roles(*roles, error_message=None)banned_roles("Muted")allowed_channels#
Lets the command run only in these channels.
allowed_channels(*channels, error_message=None)allowed_channels("bot-commands", error_message="Use this in #bot-commands.")banned_channels#
Stops the command in these channels.
banned_channels(*channels, error_message=None)set_error#
Stops the script at once and shows your message as an error.
set_error(message)amount = int(amount)
if amount <= 0:
set_error("The amount must be more than 0.")set_error works everywhere, including events. In a command, the message is the reply.
Tip
You can also set some rules on the dashboard, with no code. Open a command and pick Allowed roles and Allowed channels.