Application commands

Application commands are the native way to use an application in Moymo. A member types / in a text channel and sees the commands of every application whose bot is in the server; or right-clicks a member or a message and chooses a command under Apps. This page is the guide; every field and endpoint is in the reference.

Kinds of commands

Kind	How a member uses it
Slash command (type 1)	Types /roll 2d6. Options are filled in with suggestions and checks
User command (type 2)	Right-clicks a member and chooses it. Your application receives the member as target_id
Message command (type 3)	Right-clicks a message and chooses it. Your application receives the message in resolved.messages

A slash command has a name (lowercase letters, digits, - and _, up to 32), a description (up to 100 characters) and up to 25 options. It can be organised in sub-commands (/server info) and groups of them (/server roles list), one level deep: a command has either sub-commands or values, never both.

Options

Type	Value	The member picks or types
String	3	Text. min_length, max_length, choices, autocomplete
Integer	4	A whole number. min_value, max_value, choices, autocomplete
Boolean	5	True or false
User	6	A member of the server
Channel	7	A channel. channel_types narrows the list
Role	8	A role
Mentionable	9	A member or a role
Number	10	Any number. min_value, max_value, choices, autocomplete

Required options come before the optional ones. Choices (up to 25) make a fixed menu: only those values are accepted. Autocomplete makes your application suggest values while the member types (see Receiving and responding); a choice list and autocomplete cannot be combined.

Registering commands

You register commands from your code with the bot token: see the reference for each call.

• Global commands (/applications/@me/commands) are in every server your bot is in. Up to 100 slash commands and 15 of each context-menu kind.
• Server commands (/applications/@me/servers/{server.id}/commands) exist in one server only. Use them for what only that server needs, or to try a change in a test server first. The bot has to be in the server.
• Bulk overwrite (PUT) takes your whole list and makes the application's commands exactly that. Call it when your program starts, so what is registered is what your code handles.

Registering a name that exists changes that command, so repeating a registration is safe. A command change shows at once; there is no waiting for it to spread.

RequestPUT/applications/@me/commands

JavaScript

const commands = [
  {
    name: 'roll',
    description: 'Roll some dice',
    options: [{
      type: 4,
      name: 'sides',
      description: 'How many sides',
      required: true,
      min_value: 2,
      max_value: 100
    }]
  },
  { type: 2, name: 'Show profile' }
]

await fetch('https://moymo.net/api/app/v1/applications/@me/commands', {
  method: 'PUT',
  headers: {
    Authorization: `Bot ${process.env.MOYMO_BOT_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(commands)
})

Python

import os
import requests

commands = [
    {
        "name": "roll",
        "description": "Roll some dice",
        "options": [{
            "type": 4,
            "name": "sides",
            "description": "How many sides",
            "required": True,
            "min_value": 2,
            "max_value": 100,
        }],
    },
    {"type": 2, "name": "Show profile"},
]

requests.put(
    "https://moymo.net/api/app/v1/applications/@me/commands",
    headers={"Authorization": f"Bot {os.environ['MOYMO_BOT_TOKEN']}"},
    json=commands,
)

Who sees a command

A command appears for a member when all of these are true:

1. Your application has a verified interactions endpoint.
2. Your bot is in the server.
3. The member can send messages in the channel, and holds every bit of the command's default_member_permissions there. Set it to "0" for administrators only, or to a permission such as "32" (Manage Messages) for moderators. Leave it out for everybody.

A server's owner or administrators can remove your bot to take its commands away.

Names in other languages

name_localizations and description_localizations give a command names in other languages ({ "cs": "hod" }), with the same rules as the originals. Localised names are stored and returned today; Moymo for Windows shows the original name for now.

Designing a good command

• Name what it does. /roll, not /dice-roller-utility.
• Prefer options to typing a syntax. /roll sides:20, not /roll d20+3.
• Use choices for a short fixed list, autocomplete for a long or changing one.
• Answer fast. Three seconds is the limit; defer when you need longer.
• Use ephemeral answers for errors and private things, so a channel is not filled with them.
• Register on start-up with a bulk overwrite, so removing a command from your code removes it from Moymo.

What is not here yet

• The attachment option type (11) is refused with a clear message.
• Commands in direct messages and commands installed by a member (not a server) are not part of Moymo.
• Per-server overrides of who may use a command, by role or channel (Discord's command permissions): the default permissions are the only gate for now.