Command settings

This page covers the settings slash, context and builder commands all share: who sees them, where they work, their translated names and descriptions, and their cooldown. You're assumed to have a bot named "my-bot" logged in and a command, structure or builder, to set them on.

How settings work

Every one of these settings exists twice: as a structure entry, next to description and trigger, and as a property on the builder object. Both end up on the same command; use whichever form matches how the command was declared.

slash command roll <sides: integer>:
    description: Roll a dice
    enabled for: manage server
    contexts: guild, bot dm
    cooldown: 5 seconds
    trigger:
        reply with hidden "You rolled between 1 and %{_sides}%"

Who sees a command

enabled for lists the permissions a member needs to see and use the command by default; administrators can always use it, and an empty list means everyone can. disabled hides the command from everyone but administrators, regardless of enabled for. Both are defaults only: a guild's own integration settings, changed by a member with Manage Server, can still override them on Discord's side.

set {_ban} to a new slash command named "ban" with description "Ban a member"
set enabled for of {_ban} to ban members

A slash command mod root merged from subcommands (see Slash commands) without its own descriptor inherits enabled for as the intersection of what its subcommands allow: a permission has to be on every subcommand to end up on the root.

Where a command is available

contexts narrows which surfaces the command can be used from: guild (Discord's default, the only one set if you leave this out), bot dm, and group dm. integration types narrows how it got installed: guild install, the default, or user install, which puts the command in a user's own command list, usable in servers that never installed the bot.

set {_roll} to a new slash command named "roll" with description "Roll a dice"
set contexts of {_roll} to guild and bot dm

Translations

A structure's name: and description: sections hold one locale: text line per language; a description: section needs an en-US (or en) line as the default shown everywhere else. name: never needs one, since the header already gives the default name.

slash command greet <who: user>:
    description:
        en-US: Greet someone
        fr: Saluer quelqu'un
    name:
        fr: saluer
    arguments:
        who: Who to greet
    trigger:
        reply with hidden "Hello %{_who}%!"

A builder, its options, subcommands, groups and choices (name only) take localize the name/description of instead, one call per locale:

set {_cmd} to a new slash command named "ban" with description "Ban a member"
localize the name of {_cmd} in "fr" to "bannir"
localize the description of {_cmd} in "fr" to "Bannir un membre"

Read the translations back with name localizations of {_cmd} and description localizations of {_cmd}, both a list of "locale: text" lines. Locales are Discord's own codes (fr, en-GB, pt-BR...); a plain language name ("french") also works.

Cooldowns

cooldown blocks reuse for a timespan; cooldown scope decides who shares that timer.

An on cooldown: section reacts to a blocked call, with remaining cooldown set:

slash command slow:
    description: 10 seconds cooldown
    cooldown: 10 seconds
    cooldown scope: user
    on cooldown:
        reply with hidden "Wait %remaining cooldown%"
    trigger:
        reply with hidden "Not on cooldown!"

Without an on cooldown: section, DiSky answers by itself: an ephemeral "You can use this command again in <time>.", so the interaction is never left unacknowledged. The generic on slash command cooldown event (also on user command cooldown, on message command cooldown, on application command cooldown) fires too, and is cancellable: cancelling it lets the command run anyway and leaves the interaction to the trigger to answer. A reload resets every cooldown, since it starts from a fresh model; see Registering commands.

Errors you may see