diff --git a/docs/guides/application-commands/01-getting-started.md b/docs/guides/application-commands/01-getting-started.md new file mode 100644 index 000000000..28d5fc817 --- /dev/null +++ b/docs/guides/application-commands/01-getting-started.md @@ -0,0 +1,25 @@ +# Getting started with application commands. + +Welcome! This guide will show you how to use application commands. If you have extra questions that aren't covered here you can come to our [Discord](https://discord.com/invite/dvSfUTet3K) server and ask around there. + +## What is an application command? + +Application commands consist of three different types. Slash commands, context menu User commands and context menu Message commands. +Slash commands are made up of a name, description, and a block of options, which you can think of like arguments to a function. The name and description help users find your command among many others, and the options validate user input as they fill out your command. +Message and User commands are only a name, to the user. So try to make the name descriptive. They're accessed by right clicking (or long press, on mobile) a user or a message, respectively. + +All three varieties of application commands have both Global and Guild variants. Your global commands are available in every guild that adds your application. You can also make commands for a specific guild; they're only available in that guild. The User and Message commands are more limited in quantity than the slash commands. For specifics, check out their respective guide pages. + +An Interaction is the message that your application receives when a user uses a command. It includes the values that the user submitted, as well as some metadata about this particular instance of the command being used: the guild_id, channel_id, member and other fields. You can find all the values in our data models. + +## Authorizing your bot for application commands + +There is a new special OAuth2 scope for applications called `applications.commands`. In order to make Application Commands work within a guild, the guild must authorize your application with the `applications.commands` scope. The bot scope is not enough. + +Head over to your discord applications OAuth2 screen and make sure to select the `application.commands` scope. + +![OAuth2 scoping](images/oauth.png) + +From there you can then use the link to add your bot to a server. + +**Note**: In order for users in your guild to use your slash commands, they need to have the "Use Slash Command" permission on the guild. diff --git a/docs/guides/application-commands/context-menu-commands/creating-context-menu-commands.md b/docs/guides/application-commands/context-menu-commands/creating-context-menu-commands.md new file mode 100644 index 000000000..4e1a42987 --- /dev/null +++ b/docs/guides/application-commands/context-menu-commands/creating-context-menu-commands.md @@ -0,0 +1,82 @@ +# Creating context menu commands. + +There are two kinds of Context Menu Commands: User Commands and Message Commands. +Each of these have a Global and Guild variant. +Global menu commands are available for every guild that adds your app. An individual app's global commands are also available in DMs if that app has a bot that shares a mutual guild with the user. + +Guild commands are specific to the guild you specify when making them. Guild commands are not available in DMs. Command names are unique per application within each scope (global and guild). That means: + +- Your app cannot have two global commands with the same name +- Your app cannot have two guild commands within the same name on the same guild +- Your app can have a global and guild command with the same name +- Multiple apps can have commands with the same names + +**Note**: Apps can have a maximum of 5 global context menu commands, and an additional 5 guild-specific context menu commands per guild. + +If you don't have the code for a bot ready yet please follow [this guide](https://docs.stillu.cc/guides/getting_started/first-bot.html). + +## SlashCommandBuilder + +The slash command builder will help you create slash commands. The builder has these available fields and methods: + +| Name | Type | Description | +| --------------------- | -------------------------------- | -------------------------------------------------------------------------------------------- | +| Name | string | The name of this context menu command. | +| Description | string | A 0 length string. Left in place for possible future use. | +| WithName | Function | Sets the field name. | +| Build | Function | Builds the builder into the appropriate `CommandCreationProperties` class used to make Menu commands | + +**Note**: Context Menu command names can be upper and lowercase, and use spaces. + +Let's use the user command builder to make a global and guild command. + +```cs +// Let's hook the ready event for creating our commands in. +client.Ready += Client_Ready; + +... + +public async Task Client_Ready() +{ + // Let's build a guild command! We're going to need a guild id so lets just put that in a variable. + ulong guildId = 848176216011046962; + + // Next, lets create our user and message command builder. This is like the embed builder but for context menu commands. + var guildUserCommand = new UserCommandBuilder(); + var guildMessageCommand = new MessageCommandBuilder(); + + // Note: Names have to be all lowercase and match the regular expression ^[\w -]{3,32}$ + guildUserCommand.WithName("Guild User Command"); + guildMessageCommand.WithName("Guild Message Command"); + + // Descriptions are not used with User and Message commands + //guildCommand.WithDescription(""); + + // Let's do our global commands + var globalCommand = new UserCommandBuilder(); + globalCommand.WithName("Global User Command"); + var globalMessageCommand = new MessageCommandBuilder(); + globalMessageCommand.WithName("Global Message Command"); + + try + { + // Now that we have our builder, we can call the rest API to make our slash command. + await client.Rest.CreateGuildUserCommand(guildUserCommand.Build(), guildId); + await client.Rest.CreateGuildMessageCommand(guildMessageCommand.Build(), guildId); + + // With global commands we dont need the guild id. + await client.Rest.CreateGlobalUserCommand(globalUserCommand.Build()); + await client.Rest.CreateGlobalMessageCommand(globalMessageCommand.Build()); + } + catch(ApplicationCommandException exception) + { + // If our command was invalid, we should catch an ApplicationCommandException. This exception contains the path of the error as well as the error message. You can serialize the Error field in the exception to get a visual of where your error is. + var json = JsonConvert.SerializeObject(exception.Error, Formatting.Indented); + + // You can send this error somewhere or just print it to the console, for this example we're just going to print it. + Console.WriteLine(json); + } +} + +``` +**Note**: Application commands only need to be created once. They do _not_ have to be 'created' on every startup or connection. The example simple shows creating them in the ready event as it's simpler than creating normal bot commands to register application commands. diff --git a/docs/guides/slash-commands/02-creating-slash-commands.md b/docs/guides/application-commands/slash-commands/02-creating-slash-commands.md similarity index 100% rename from docs/guides/slash-commands/02-creating-slash-commands.md rename to docs/guides/application-commands/slash-commands/02-creating-slash-commands.md diff --git a/docs/guides/slash-commands/03-responding-to-slash-commands.md b/docs/guides/application-commands/slash-commands/03-responding-to-slash-commands.md similarity index 100% rename from docs/guides/slash-commands/03-responding-to-slash-commands.md rename to docs/guides/application-commands/slash-commands/03-responding-to-slash-commands.md diff --git a/docs/guides/slash-commands/04-parameters.md b/docs/guides/application-commands/slash-commands/04-parameters.md similarity index 100% rename from docs/guides/slash-commands/04-parameters.md rename to docs/guides/application-commands/slash-commands/04-parameters.md diff --git a/docs/guides/slash-commands/05-responding-ephemerally.md b/docs/guides/application-commands/slash-commands/05-responding-ephemerally.md similarity index 100% rename from docs/guides/slash-commands/05-responding-ephemerally.md rename to docs/guides/application-commands/slash-commands/05-responding-ephemerally.md diff --git a/docs/guides/slash-commands/06-subcommands.md b/docs/guides/application-commands/slash-commands/06-subcommands.md similarity index 100% rename from docs/guides/slash-commands/06-subcommands.md rename to docs/guides/application-commands/slash-commands/06-subcommands.md diff --git a/docs/guides/slash-commands/07-choice-slash-command.md b/docs/guides/application-commands/slash-commands/07-choice-slash-command.md similarity index 100% rename from docs/guides/slash-commands/07-choice-slash-command.md rename to docs/guides/application-commands/slash-commands/07-choice-slash-command.md diff --git a/docs/guides/slash-commands/README.md b/docs/guides/application-commands/slash-commands/README.md similarity index 99% rename from docs/guides/slash-commands/README.md rename to docs/guides/application-commands/slash-commands/README.md index 702aec6de..3b672792c 100644 --- a/docs/guides/slash-commands/README.md +++ b/docs/guides/application-commands/slash-commands/README.md @@ -1,11 +1,11 @@ -## Slash command guides - -Here you can find some guides on how to use slash commands. - -1. [Getting started](https://github.com/Discord-Net-Labs/Discord.Net-Labs/blob/Interactions/docs/guides/slash-commands/01-getting-started.md) -2. [Creating a slash command](https://github.com/Discord-Net-Labs/Discord.Net-Labs/blob/Interactions/docs/guides/slash-commands/02-creating-slash-commands.md) -3. [Responding to slash commands](https://github.com/Discord-Net-Labs/Discord.Net-Labs/blob/Interactions/docs/guides/slash-commands/03-responding-to-slash-commands.md) -4. [Parameters in slash commands](https://github.com/Discord-Net-Labs/Discord.Net-Labs/blob/Interactions/docs/guides/slash-commands/04-parameters.md) -5. [Responding ephemerally](https://github.com/Discord-Net-Labs/Discord.Net-Labs/blob/Interactions/docs/guides/slash-commands/05-responding-ephemerally.md) -6. [Subcommands](https://github.com/Discord-Net-Labs/Discord.Net-Labs/blob/Interactions/docs/guides/slash-commands/06-subcommands.md) -7. [Choices](https://github.com/Discord-Net-Labs/Discord.Net-Labs/blob/Interactions/docs/guides/slash-commands/07-choice-slash-command.md) +## Slash command guides + +Here you can find some guides on how to use slash commands. + +1. [Getting started](https://github.com/Discord-Net-Labs/Discord.Net-Labs/blob/Interactions/docs/guides/slash-commands/01-getting-started.md) +2. [Creating a slash command](https://github.com/Discord-Net-Labs/Discord.Net-Labs/blob/Interactions/docs/guides/slash-commands/02-creating-slash-commands.md) +3. [Responding to slash commands](https://github.com/Discord-Net-Labs/Discord.Net-Labs/blob/Interactions/docs/guides/slash-commands/03-responding-to-slash-commands.md) +4. [Parameters in slash commands](https://github.com/Discord-Net-Labs/Discord.Net-Labs/blob/Interactions/docs/guides/slash-commands/04-parameters.md) +5. [Responding ephemerally](https://github.com/Discord-Net-Labs/Discord.Net-Labs/blob/Interactions/docs/guides/slash-commands/05-responding-ephemerally.md) +6. [Subcommands](https://github.com/Discord-Net-Labs/Discord.Net-Labs/blob/Interactions/docs/guides/slash-commands/06-subcommands.md) +7. [Choices](https://github.com/Discord-Net-Labs/Discord.Net-Labs/blob/Interactions/docs/guides/slash-commands/07-choice-slash-command.md) diff --git a/docs/guides/slash-commands/images/ephemeral1.png b/docs/guides/application-commands/slash-commands/images/ephemeral1.png similarity index 100% rename from docs/guides/slash-commands/images/ephemeral1.png rename to docs/guides/application-commands/slash-commands/images/ephemeral1.png diff --git a/docs/guides/slash-commands/images/feedback1.png b/docs/guides/application-commands/slash-commands/images/feedback1.png similarity index 100% rename from docs/guides/slash-commands/images/feedback1.png rename to docs/guides/application-commands/slash-commands/images/feedback1.png diff --git a/docs/guides/slash-commands/images/feedback2.png b/docs/guides/application-commands/slash-commands/images/feedback2.png similarity index 100% rename from docs/guides/slash-commands/images/feedback2.png rename to docs/guides/application-commands/slash-commands/images/feedback2.png diff --git a/docs/guides/slash-commands/images/listroles1.png b/docs/guides/application-commands/slash-commands/images/listroles1.png similarity index 100% rename from docs/guides/slash-commands/images/listroles1.png rename to docs/guides/application-commands/slash-commands/images/listroles1.png diff --git a/docs/guides/slash-commands/images/listroles2.png b/docs/guides/application-commands/slash-commands/images/listroles2.png similarity index 100% rename from docs/guides/slash-commands/images/listroles2.png rename to docs/guides/application-commands/slash-commands/images/listroles2.png diff --git a/docs/guides/slash-commands/images/oauth.png b/docs/guides/application-commands/slash-commands/images/oauth.png similarity index 100% rename from docs/guides/slash-commands/images/oauth.png rename to docs/guides/application-commands/slash-commands/images/oauth.png diff --git a/docs/guides/slash-commands/images/settings1.png b/docs/guides/application-commands/slash-commands/images/settings1.png similarity index 100% rename from docs/guides/slash-commands/images/settings1.png rename to docs/guides/application-commands/slash-commands/images/settings1.png diff --git a/docs/guides/slash-commands/images/settings2.png b/docs/guides/application-commands/slash-commands/images/settings2.png similarity index 100% rename from docs/guides/slash-commands/images/settings2.png rename to docs/guides/application-commands/slash-commands/images/settings2.png diff --git a/docs/guides/slash-commands/images/settings3.png b/docs/guides/application-commands/slash-commands/images/settings3.png similarity index 100% rename from docs/guides/slash-commands/images/settings3.png rename to docs/guides/application-commands/slash-commands/images/settings3.png diff --git a/docs/guides/slash-commands/images/slashcommand1.png b/docs/guides/application-commands/slash-commands/images/slashcommand1.png similarity index 100% rename from docs/guides/slash-commands/images/slashcommand1.png rename to docs/guides/application-commands/slash-commands/images/slashcommand1.png diff --git a/docs/guides/slash-commands/images/slashcommand2.png b/docs/guides/application-commands/slash-commands/images/slashcommand2.png similarity index 100% rename from docs/guides/slash-commands/images/slashcommand2.png rename to docs/guides/application-commands/slash-commands/images/slashcommand2.png diff --git a/docs/guides/slash-commands/01-getting-started.md b/docs/guides/slash-commands/01-getting-started.md deleted file mode 100644 index 093178878..000000000 --- a/docs/guides/slash-commands/01-getting-started.md +++ /dev/null @@ -1,23 +0,0 @@ -# Getting started with slash commands. - -Welcome! This guide will show you how to use slash commands. If you have extra questions that aren't covered here you can come to our [Discord](https://discord.com/invite/dvSfUTet3K) server and ask around there. - -## What is a slash command? - -Slash Commands _(synonymous with application commands)_ are made up of a name, description, and a block of options, which you can think of like arguments to a function. The name and description help users find your command among many others, and the options validate user input as they fill out your command. - -Your global commands are available in every guild that adds your application. You can also make commands for a specific guild; they're only available in that guild. - -An Interaction is the message that your application receives when a user uses a command. It includes the values that the user submitted, as well as some metadata about this particular instance of the command being used: the guild_id, channel_id, member and other fields. You can find all the values in our data models. - -## Authorizing your bot for slash commands - -There is a new special OAuth2 scope for applications called `applications.commands`. In order to make Slash Commands work within a guild, the guild must authorize your application with the `applications.commands` scope. The bot scope is not enough. - -Head over to your discord applications OAuth2 screen and make sure to select the `application.commands` scope. - -![OAuth2 scoping](images/oauth.png) - -From there you can then use the link to add your bot to a server. - -**Note**: In order for users in your guild to use your slash commands, they need to have the "Use Slash Command" permission on the guild.