Chat Commands

Privileged Intents and You

Chat commands require the use of the "message content" privileged intent. While chat commands were traditionally how users interacted with bots on Discord, this is no longer what Discord recommends or encourages for your bots.

If your bot is on 75 or more guilds (or you plan to grow it to that point), you should consider using Application Commands instead of chat commands as much as possible.

Your bot will need to go through a verification process (which starts at 75 guilds) before it can join over 100 guilds. Discord will not verify bots that are using the "message content" privileged intent without a good reason for it.

The only situations that we advise you to use chat commands for are those where the other types of commands provide an objectively worse user experience. This largely only applies to commands that need to take a large amount of text as input (where modals do not suffice), or where your bot needs to make use of file attachments uploaded to Discord without downloading them.

Additionally, it's worth noting that the Discord client encourages users to make use of Slash Commands when they attempt to use a chat command. This means that users will expect your bots to support Application Commands as a default mode of interaction.

Please don't skip over the above admonitions — they're important!

Introduction

Chat commands are a fairly simple concept. When a user sends a message starting with a command prefix (or bot mention), the command name and arguments, Kord Extensions can process it accordingly.

All builder functions should be called within your bot's setup function when you're registering commands before the bot starts up. However, it is also possible to register commands later on in the bot's lifecycle by calling the same functions.

Chat commands support command arguments, which are specified as explained on the commands overview page. However, unlike the other command types, they do not support Modals.

As Discord recommends against using chat commands, they must be enabled before they can be used. For more information, see the configuration documentation.

chatCommand(::MyArguments) { name = "my-command" description = "Description explaining command usage." check { hasPermission(Permission.MentionEveryone) } aliases = arrayOf("my", "mycommand") action { message.respond( "Hey, ${arguments.user.mention}! Get pinged!" ) } }

Extension API

The following APIs are available on the Extension type, which you can use to define your chat commands and modify their behavior.

Builders

Name	Receiver	Description
`chatCommandCheck`	`CheckWithCache <MessageCreateEvent>`	Register a check that must pass for the `action` belonging to all chat commands defined within this extension to be run. For more information on checks, see the dedicated documentation.
`chatCommand`	`ChatCommand`	Register a standalone chat command. This builder function optionally takes the constructor of an arguments class as the first argument, representing this command's arguments to be supplied on Discord.
`chatGroupCommand`	`ChatGroupCommand`	Register a grouped chat command. This builder function optionally takes the constructor of an arguments class as the first argument, representing this command's arguments to be supplied on Discord.

Standalone Commands

Standalone commands are the simplest type of chat command, and they're defined using the chatCommand builder function. This builder is a receiver function against the ChatCommand type, which provides a number of APIs that can be used to configure your command and its metadata.

At minimum, a command must have a name, description and action defined.

The following APIs are available for use when writing a chat command, in addition to those provided by the base Command type.

Builders

Name	Receiver	Description
Required Builders
`action`	`ChatCommandContext <Arguments>`	Required: Register the command's action, which will be run when the command is invoked.
Optional Builders
`check`	`CheckWithCache <MessageCreateEvent>`	Register a check that must pass for the command's `action` to be run. For more information on checks, see the dedicated documentation.

Properties

	Name	Type	Description
Required Properties
🌐	`description`	`String`	Required: The command's description. This should be a string that explains what the command does. If the string spans multiple lines, the first line should be a short summary of what the command does, with a blank line underneath.
🌐	`name`	`String`	Required: The command's name, which is used to identify the command internally and for invoking the command on Discord.
Optional Properties
	`aliases`	`Array <String>`	Array of alternative names that may be used to invoke this command. If an alias conflicts with the name of another command, the other command will take priority. Ignored if `aliasKey` is set.
	`allowKeywordArguments`	`Boolean`	Whether to allow the parser to parse arguments in the form of `key=value` or `--key value`. Defaults to `true`.
	`enabled`	`Boolean`	Whether this command is currently enabled, which can be changed at runtime if needed. When disabled, a command can't be invoked and won't be shown in help commands. Defaults to `true`.
	`hidden`	`Boolean`	Whether this command should be hidden from help command listings. Hidden commands may still be invoked. Defaults to `false`.
	`localeFallback`	`Boolean`	By default, translated command names may be invoked based on the bot's configured locale resolvers. By setting this property to `true`, Kord Extensions will attempt to find a command using the bot's default locale when it can't be found under the resolved one. Defaults to `false`.
Translation-Related Properties
🌐	`aliasKey`	`String?`	Translation key referencing a comma-separated list of alternative command names. If this property is set, the `aliases` list is ignored.
🌐	`signature`	`String?`	Translation key referencing the command signature to be shown in help commands. By default, Kord Extensions will generate a signature automatically. This property may be set if you wish to override it. Command signatures should not include the command name. Example signature: `<required: user> [option: string = default...]`

Grouped Commands

Grouped commands are a special type of chat command that contains subcommands. They work just like a standalone chat command, but with the addition of a set of functions that allow you to nest other commands within them. They're defined using the chatGroupCommand builder function.

To execute a grouped command, you provide the command prefix, name and arguments the same way you do with a standalone command. However, the first argument provided to the grouped command will be matched against the names of any nested commands, and removed from the list of arguments provided to the found command.

Grouped commands may contain subcommands or nested grouped commands. There is no limit on how deep you may nest grouped commands, but we recommend you avoid nesting them more than once, for the sake of clarity and ease of use.

The grouped command's action is executed when the command is executed without any arguments, or when none of the nested commands match the first argument provided to it. A default action block is provided, which shows help information about the command and its nested commands. However, you may provide your own if needed or desirable.

The following APIs are available for use when writing a grouped chat command, in addition to those provided by the base ChatCommand type..

Builders

Name	Description
`chatCommand`	Define a subcommand. This builder function mirrors the behavior of the `chatCommand` builder function defined at `Extension` level, which you'd normally use to register standalone commands. Subcommands inherit the checks that are defined in their parent commands.
`chatGroupCommand`	Define a grouped subcommand. This builder function allows you to nest grouped commands as deeply as is required. It mirrors the behavior of the `chatGroupCommand` builder function defined at `Extension` level. Subcommands inherit the checks that are defined in their parent commands.

Command Context

The ChatCommandContext type is the receiver for all chat command action blocks. This type provides relevant APIs on top of the base command context object type, allowing you to efficiently respond to command invocations.

The following additional APIs are provided:

Builders

Name	Receiver	Description
`paginator`	`PaginatorBuilder`	Convenience function, allowing you to easily create a button-based paginator. The following parameters are supported: `defaultGroup = ""` - The default paginator group. `pingInReply = true` - Whether to ping the author of the `targetMessage` in reply, if it's specified. `targetChannel` - Channel to send the paginator to. Required if `targetMessage` is not specified. `targetMessage` - Message to send the paginator in response to. Required if `targetChannel` is not specified. Note: This will not send the paginator automatically. You'll need to call the `send` function on this function's return value to send it. For more information on paginators (and the paginator builder), see the dedicated documentation.

Name

Receiver

Description

paginator

PaginatorBuilder

Convenience function, allowing you to easily create a button-based paginator. The following parameters are supported:

defaultGroup = "" - The default paginator group.
pingInReply = true - Whether to ping the author of the targetMessage in reply, if it's specified.
targetChannel - Channel to send the paginator to. Required if targetMessage is not specified.
targetMessage - Message to send the paginator in response to. Required if targetChannel is not specified.

Note: This will not send the paginator automatically. You'll need to call the send function on this function's return value to send it.

For more information on paginators (and the paginator builder), see the dedicated documentation.

Functions

Name	Parameters	Description
`sendHelp`		Generate and send help information for this command. Returns `true` when a help extension is loaded and the help message was sent, and `false` otherwise.
Translation-Related Functions
`Message.respondTranslated`	🌐 `key`, `replacements`, `useReply = true`	Convenience function that allows you to respond to a message with translated content, using the resolved locale for this command context. This makes use of the `respond` message utility function, with the `useReply` parameter directly provided to it. For more information, see the dedicated documentation.

Name

Parameters

Description

sendHelp

Generate and send help information for this command. Returns true when a help extension is loaded and the help message was sent, and false otherwise.

Translation-Related Functions

Message.respondTranslated

🌐 key, replacements, useReply = true

Convenience function that allows you to respond to a message with translated content, using the resolved locale for this command context. This makes use of the respond message utility function, with the useReply parameter directly provided to it.

For more information, see the dedicated documentation.

Properties

Name	Type	Description
`arguments`	`T: Arguments`	The command's arguments, parsed into the arguments class you specified the constructor for when you registered this command. If you don't specify the aforementioned constructor, this will be an empty `Arguments` object.
Data Properties
`channel`	`MessageChannelBehavior`	Object representing the channel this command was invoked within.
`guild`	`GuildBehavior?`	Object representing the guild this command was invoked within, or `null` if it was invoked in a DM.
`member`	`MemberBehavior?`	Object representing the member that executed this command, or `null` if it was invoked in a DM or by a webhook.
`message`	`Message`	Object representing the message that invoked this command.
`user`	`UserBehavior?`	Object representing the user that executed this command, or `null` if it was invoked by a webhook.

Last modified: 03 September 2024