Slash commands
A bot registers commands over its API; members run them from the composer by typing /, and the bot answers over the REST API.
Register
PUT /api/bot/v1/commands replaces all of a bot's commands at once; POST adds or updates one by name; GET lists them and DELETE /commands/{id} removes one.
{"name": "ping", "description": "Replies with pong",
"options": [{"name": "text", "description": "What to say", "type": 3, "required": true}]}
- Names are 1 to 32 lowercase letters, digits,
-or_. - At most 50 commands per bot and 10 options per command. Commands an admin disabled are kept by a bulk
PUTand count toward the 50. - Option types:
3string,4integer,5boolean,6user (a member's ID),7channel (an ID). Required options come first. - A string option may list
choices(at most 25, each 1 to 100 characters, unique): the composer shows them as a list and the server refuses any other value.
Where members see them
Commands are not tied to channels by the bot. A member sees a command in the composer of every channel where the bot can view and send, so the admin's channel permissions for the bot are the command's scope. Running one needs Send messages in that channel. Admins see all of a bot's commands in the Bots tab and can disable any of them; a disabled command stays off even when the bot registers it again, and the bot cannot delete or re-create it (404).
A run
A member's run is validated on the server (types, required options, members and channels the caller can see) and delivered to one live gateway session of the bot as INTERACTION_CREATE. No intent is needed. The member's request answers 202, or 409 when the bot is not connected. Each member can run at most 20 commands a minute.
{"op": 0, "t": "INTERACTION_CREATE", "s": 7, "d": {
"id": "...", "token": "...", "type": 2, "channel_id": "...", "application_id": "<bot id>",
"data": {"id": "<command id>", "name": "ping", "options": [{"name": "text", "type": 3, "value": "hello"}]},
"member": {"user": {"id": "...", "username": "max", "display_name": "Max", "avatar_url": "/api/media/..."}}}}
Answer it within 15 minutes with the id and token from the event: see Interactions.
Built-in commands
The server has commands of its own in the same menu, marked Built-in and listed first: /poll, /me, /shrug, /tableflip, /unflip, /spoiler, /msg, /nick, /thread, /timeout, /ban and /kick. A bot may register a command with the same name; it is listed next to the built-in one, not instead of it.
With an SDK
await client.commands.set([
{ name: 'roll', description: 'Rolls a die',
options: [{ name: 'sides', description: 'How many sides', type: OptionType.Integer, required: true }] },
])
_, err := c.REST.SetCommands(ctx, []mnema.CommandInput{
{Name: "roll", Description: "Rolls dice", Options: []mnema.CommandOption{
{Name: "sides", Description: "Sides of each die", Type: mnema.OptionInteger},
}},
})