Registering commands

This page covers the three effects that push slash, context and builder commands to Discord, and reading back what's already registered. You're assumed to have a bot named "my-bot" logged in and at least one command declared, structure or builder.

How registration works

Nothing reaches Discord on its own: a slash command structure and a new slash command builder are both just models until a script runs one of three effects on them.

on guild ready:
    update the discord commands (all structured application commands) in event-guild

all structured application commands collects every slash command, user command and message command structure into one list, so a builder command joins the same call: update the discord commands (all structured application commands) and {_roll} in event-guild. Every one of the three effects blocks until Discord answers and never takes await; a failure on Discord's side goes through the error layer.

Guild or global

in event-guild applies immediately and is scoped to that one guild; globally in event-bot applies to every guild the bot is in, but can take up to an hour to show up for users. Guild registration belongs in on guild ready, which fires for every guild the bot is in (including ones it joins later); global registration belongs in on ready, which fires once. See Starting a bot for how the two lifecycle events differ.

on ready:
    set {_ping} to a new slash command named "ping" with description "Pong!"
    update the discord commands {_ping} globally in event-bot

Pushing the same command both ways makes Discord show it twice: guild-scoped and global commands are separate lists, not one merged into the other. Discord also limits how often a guild's whole list can be replaced with update: 200 times a day.

Adding and removing one command

register and unregister change one command without replacing the whole list.

on guild ready:
    set {_roll} to a new slash command named "roll" with description "Roll a dice"
    register the discord command {_roll} in event-guild

register also takes several commands at once: register the discord commands {_a} and {_b} globally in event-bot. unregister accepts a command object, a name, or a raw id, and a shorthand for everything:

unregister the discord command "ping" from event-guild
unregister the discord command {_roll} from event-guild
unregister all the discord commands from event-guild

A command object with a known command id is deleted directly; a name is looked up among the registered commands first, so it costs an extra request.

Reading what Discord has

registered commands of asks Discord for the live list of a guild or a bot's global commands, as regular command objects with their command id already set. It's a retrieve, so it needs await:

await set {_cmds::*} to registered commands of event-guild
loop {_cmds::*}:
    send "%name of loop-value% (%command id of loop-value%, %command type of loop-value%)" to console

A retrieved command can be edited and pushed back with register, upserting it by name:

await set {_cmds::*} to registered commands of event-guild
loop {_cmds::*}:
    if name of loop-value is "roll":
        set disabled of loop-value to true
        register the discord command loop-value in event-guild

Reload and shutdown

A slash command or context command structure is a model, not a live registration: reloading a script swaps the model, and the command already pushed to Discord keeps working, bound to whichever model matches its full path at the time it's used. on cooldown cooldowns are part of that model, so a reload also resets them.

Errors you may see