Ajouter des commandes slash (/) avec Discord.js v14
Les commandes slash (barre oblique) sont les commandes de bot, avec description et paramètres, que Discord affiche lorsque l'utilisateur tape / dans la zone de message. C'est Discord qui contrôle les paramètres ; le bot ne lit pas le texte du message, il reçoit à la place un objet interaction et y répond. Ce guide s'adresse aux utilisateurs de discord.js v14 ; les autres guides sur les bots se trouvent sur la page Guides bot Discord.
Avant de commencer
- Application du bot et token : la création de l'application dans le Developer Portal, l'obtention du token (la clé de connexion du bot) et le fichier
.envsont expliqués dans le guide Comment créer un bot Discord à partir de zéro avec Discord.js v14. Nous reprenons ici la même structure :.envcontientDISCORD_TOKEN,CLIENT_ID(Application ID) etGUILD_ID(l'identifiant du serveur de test). - Node.js : discord.js 14.27.0 exige au minimum Node.js 18 ; le guide discord.js recommande la version LTS (support à long terme) actuelle. Le flag
--env-fileutilisé dans les scripts nécessite au minimum Node.js 20.6.0. Vous voyez les versions installées avecnode -vetnpm ls discord.js. applications.commands(scope) : l'application ne peut créer des commandes sur un serveur que si elle y a été autorisée avec ce scope. D'après la documentation de Discord, ce scope est inclus par défaut avec le scopebot; si les commandes n'apparaissent pas pour un bot ajouté avec une ancienne invitation, ajoutez de nouveau le bot avec un lien d'invitation à jour.- Scripts de
package.json: la sectionscriptsdoit se présenter ainsi :"scripts": { "start": "node --env-file=.env index.js", "deploy": "node --env-file=.env deploy-commands.js" } - Windows et Linux : le code est identique ; vous exécutez les commandes dans le dossier du projet, avec PowerShell sous Windows et dans le terminal SSH sur un VDS Linux. Pour le serveur sur lequel le bot restera allumé en permanence, les offres VDS pour bot Discord comprennent 4 CPU, 2–4 Go de RAM et 30–40 Go de disque NVMe.
1. Comprendre les deux parties d'une commande et la structure des dossiers
Chaque commande slash comporte deux parties. Définition (data) : nom, description, options et permissions ; elle est enregistrée auprès de Discord et y est conservée. Code (execute) : la fonction exécutée par votre bot quand la commande est utilisée ; Discord ne la voit pas. Chaque commande est un fichier distinct, placé dans un sous-dossier de commands :
discord-bot/
├── commands/
│ └── utility/
│ ├── ping.js
│ ├── des.js
│ ├── lent.js
│ ├── annonce.js
│ └── faq.js
├── .env
├── charger-commandes.js
├── deploy-commands.js
├── index.js
└── package.json
Créez le dossier à la racine du projet. Windows (PowerShell) :
mkdir commands\utility
Linux :
mkdir -p commands/utility
2. Écrire le premier fichier de commande
data se construit avec SlashCommandBuilder. Fichier commands/utility/ping.js :
const { SlashCommandBuilder } = require('discord.js');
module.exports = {
data: new SlashCommandBuilder()
.setName('ping')
.setDescription('Vérifie si le bot répond.'),
async execute(interaction) {
await interaction.reply('Pong!');
},
};
Règles de nommage : 1 à 32 caractères, en minuscules, sans espace ; en dehors des lettres et des chiffres, seuls - et _ sont autorisés. Les lettres minuscules accentuées (é, è, à, ç) sont également valides. La description est obligatoire et fait de 1 à 100 caractères. setName() et setDescription() valident la valeur immédiatement : un nom non conforme lève une erreur dès le chargement du fichier.
3. Ajouter des options, des choix prédéfinis et des limites
Les options sont les paramètres de la commande ; leurs règles de nommage sont les mêmes que pour le nom de la commande, et la description est obligatoire. setRequired(true) rend l'option obligatoire ; Discord exige que les options obligatoires précèdent les options facultatives. Aux options de texte et de nombre, vous pouvez ajouter avec addChoices() jusqu'à 25 choix prédéfinis (choices) ; l'utilisateur ne peut alors choisir que l'un d'eux : la liste affiche name et le bot reçoit value. commands/utility/des.js :
const { SlashCommandBuilder } = require('discord.js');
module.exports = {
data: new SlashCommandBuilder()
.setName('des')
.setDescription('Lance un ou plusieurs dés.')
.addIntegerOption((option) =>
option
.setName('faces')
.setDescription('Nombre de faces du dé')
.setRequired(true)
.addChoices(
{ name: '6 faces', value: 6 },
{ name: '20 faces', value: 20 },
),
)
.addIntegerOption((option) =>
option
.setName('nombre')
.setDescription('Nombre de dés à lancer (1-10)')
.setMinValue(1)
.setMaxValue(10),
),
async execute(interaction) {
const faces = interaction.options.getInteger('faces');
const nombre = interaction.options.getInteger('nombre') ?? 1;
const resultat = Array.from({ length: nombre }, () => Math.floor(Math.random() * faces) + 1);
await interaction.reply(`${nombre} dé(s) à ${faces} faces : ${resultat.join(', ')}`);
},
};
setMinValue()/setMaxValue()limitent la plage des valeurs numériques, etsetMinLength()/setMaxLength()la longueur du texte ; Discord refuse toute valeur hors limites.- Une option facultative laissée vide renvoie
null; utilisez??pour fournir une valeur par défaut. - Une commande peut avoir au maximum 25 options ; les autres types figurent dans le tableau en fin de guide.
4. Mettre en place le gestionnaire de commandes (handler)
Le gestionnaire charge les fichiers du dossier commands et transmet chaque interaction reçue au bon fichier selon le nom de la commande. La boucle de chargement est partagée par le bot et par le script d'enregistrement ; si vous utilisez le modèle du guide d'installation, les fichiers ci-dessous remplacent ceux qui s'y trouvent. À la racine du projet, charger-commandes.js :
const fs = require('node:fs');
const path = require('node:path');
module.exports = function chargerCommandes() {
const commandes = [];
const racine = path.join(__dirname, 'commands');
const dossiers = fs.readdirSync(racine, { withFileTypes: true }).filter((e) => e.isDirectory());
for (const dossier of dossiers) {
const cheminDossier = path.join(racine, dossier.name);
const fichiers = fs.readdirSync(cheminDossier).filter((fichier) => fichier.endsWith('.js'));
for (const fichier of fichiers) {
const commande = require(path.join(cheminDossier, fichier));
if ('data' in commande && 'execute' in commande) commandes.push(commande);
else console.log(`[AVERTISSEMENT] ${fichier} : data ou execute manquant.`);
}
}
return commandes;
};
index.js :
const { Client, Collection, Events, GatewayIntentBits, MessageFlags } = require('discord.js');
const chargerCommandes = require('./charger-commandes');
const client = new Client({ intents: [GatewayIntentBits.Guilds] });
client.commands = new Collection();
for (const commande of chargerCommandes()) client.commands.set(commande.data.name, commande);
client.once(Events.ClientReady, (pret) => {
console.log(`Prêt : ${pret.user.tag}`);
});
client.on(Events.InteractionCreate, async (interaction) => {
if (interaction.isAutocomplete()) {
const commande = interaction.client.commands.get(interaction.commandName);
try {
await commande?.autocomplete?.(interaction);
} catch (error) {
console.error(error);
}
return;
}
if (!interaction.isChatInputCommand()) return;
const commande = interaction.client.commands.get(interaction.commandName);
if (!commande) {
console.error(`Aucune commande nommée ${interaction.commandName} n'a été trouvée.`);
return;
}
try {
await commande.execute(interaction);
} catch (error) {
console.error(error);
const reponse = { content: "Une erreur s'est produite pendant l'exécution de la commande.", flags: MessageFlags.Ephemeral };
const envoi = interaction.replied || interaction.deferred
? interaction.followUp(reponse)
: interaction.reply(reponse);
await envoi.catch(console.error);
}
});
client.login(process.env.DISCORD_TOKEN);
Collectionest une classe discord.js qui étend la structureMap; les commandes y sont stockées sous leur nom et retrouvées avecinteraction.commandName.Events.InteractionCreatese déclenche à chaque interaction, boutons et menus compris ;isChatInputCommand()ne laisse passer que les commandes slash, etisAutocomplete()les demandes de suggestions de l'étape 8. Les boutons sont expliqués dans le guide Comment utiliser les boutons et les menus déroulants (select menu) dans Discord.js v14 ?.- Pour les commandes slash, l'intent
GatewayIntentBits.Guilds(autorisation d'événements) suffit. - Le
.catch()final est indispensable : la réponse d'erreur à une interaction expirée échoue elle aussi, et une erreur de Promise non interceptée met fin par défaut au processus Node.js.
5. Enregistrer les commandes auprès de Discord (REST)
Les définitions de commandes ne s'enregistrent que via l'API REST. À la racine du projet, deploy-commands.js :
const { REST, Routes } = require('discord.js');
const chargerCommandes = require('./charger-commandes');
const { DISCORD_TOKEN, CLIENT_ID, GUILD_ID } = process.env;
const estGlobal = process.argv.includes('global');
const vider = process.argv.includes('vider');
const body = vider ? [] : chargerCommandes().map((commande) => commande.data.toJSON());
const route = estGlobal
? Routes.applicationCommands(CLIENT_ID)
: Routes.applicationGuildCommands(CLIENT_ID, GUILD_ID);
const rest = new REST().setToken(DISCORD_TOKEN);
(async () => {
try {
const data = await rest.put(route, { body });
console.log(`${data.length} commandes enregistrées ${estGlobal ? 'globalement' : 'sur le serveur de test'}.`);
} catch (error) {
console.error(error);
}
})();
Utilisation (identique sous Windows et sous Linux) :
npm run deploy
npm run deploy global
npm run deploy vider
La première commande enregistre sur le serveur de test, la deuxième effectue l'enregistrement global et la troisième supprime les commandes du serveur de test ; npm transmet au script le mot placé après le nom du script.
- Les commandes de serveur (guild) (
Routes.applicationGuildCommands()) n'apparaissent que sur le serveurGUILD_IDet sont mises à jour immédiatement ; elles servent au développement. - Les commandes globales (
Routes.applicationCommands()) apparaissent sur tous les serveurs où l'application est autorisée et, par défaut, dans les messages privés (MP) du bot. La documentation actuelle de Discord n'indique aucun délai d'attente : si un utilisateur emploie une ancienne version de la commande, Discord rejette la requête et met la commande à jour dans son client. L'information « jusqu'à une heure » des anciennes sources ne figure pas dans la documentation actuelle. PUTremplace entièrement la liste de cette portée : une commande dont vous avez supprimé le fichier avant de réenregistrer disparaît.- Discord applique une limite de 200 créations de commandes par jour et par serveur (au-delà :
DiscordAPIError[30034]) ; ne lancez le script que lorsque les définitions changent et ne le placez pas au démarrage du bot.
6. Répondre dans les 3 secondes
Discord attend une première réponse à chaque interaction dans les 3 secondes ; passé ce délai, le jeton (token) d'interaction devient invalide et la commande apparaît comme ayant échoué. Pour les tâches longues, comme une requête en base de données ou un appel à une API externe, accusez d'abord réception de l'interaction avec deferReply() ; l'utilisateur voit l'indicateur « réfléchit » et vous envoyez le résultat avec editReply(). Après la première réponse, le jeton reste valide 15 minutes ; pendant ce temps, vous pouvez envoyer des messages supplémentaires avec followUp(). commands/utility/lent.js simule une tâche de 5 secondes :
const { setTimeout: attendre } = require('node:timers/promises');
const { MessageFlags, SlashCommandBuilder } = require('discord.js');
module.exports = {
data: new SlashCommandBuilder().setName('lent').setDescription('Simule une tâche longue.'),
async execute(interaction) {
await interaction.deferReply({ flags: MessageFlags.Ephemeral });
await attendre(5000); // dans un vrai bot : appel à une base de données ou à une API
await interaction.editReply('Tâche terminée en 5 secondes.');
},
};
MessageFlags.Ephemeral : une réponse envoyée avec ce flag n'est visible que par la personne qui a utilisé la commande, et ce réglage ne peut pas être modifié ensuite ; si la réponse différée doit rester privée, passez le flag dans deferReply().
7. Limiter la commande par permission et par contexte
/annonce envoie un message dans le salon choisi ; seuls les membres disposant de la permission « Gérer les messages » doivent pouvoir l'utiliser, et elle ne doit pas apparaître en MP. commands/utility/annonce.js :
const {
ApplicationIntegrationType, ChannelType, InteractionContextType, MessageFlags, PermissionFlagsBits,
SlashCommandBuilder,
} = require('discord.js');
module.exports = {
data: new SlashCommandBuilder()
.setName('annonce')
.setDescription('Envoie une annonce dans le salon choisi.')
.addStringOption((option) =>
option.setName('texte').setDescription("Texte de l'annonce").setRequired(true).setMaxLength(2000),
)
.addChannelOption((option) =>
option
.setName('salon')
.setDescription('Salon cible (ce salon si vide)')
.addChannelTypes(ChannelType.GuildText),
)
.setDefaultMemberPermissions(PermissionFlagsBits.ManageMessages)
.setContexts(InteractionContextType.Guild)
.setIntegrationTypes(ApplicationIntegrationType.GuildInstall),
async execute(interaction) {
const texte = interaction.options.getString('texte');
const salon = interaction.options.getChannel('salon') ?? interaction.channel;
if (!salon.permissionsFor(interaction.member)?.has(PermissionFlagsBits.SendMessages)) {
await interaction.reply({ content: "Vous n'avez pas la permission d'envoyer des messages dans ce salon.", flags: MessageFlags.Ephemeral });
return;
}
await salon.send({ content: texte, allowedMentions: { parse: [] } });
await interaction.reply({ content: `Annonce envoyée dans ${salon}.`, flags: MessageFlags.Ephemeral });
},
};
setDefaultMemberPermissions()définit la permission requise par défaut pour utiliser la commande. Avec la valeur0, seuls les membres ayant la permission « Administrateur » et ceux à qui une autorisation spécifique a été accordée peuvent utiliser la commande ; les membres disposant de la permission « Administrateur » ne peuvent être privés d'aucune commande.- Ce sont des valeurs par défaut : les utilisateurs habilités peuvent modifier les permissions des commandes par rôle, par utilisateur et par salon dans la section « Paramètres du serveur → Intégrations ».
setContexts(InteractionContextType.Guild)limite la commande globale aux serveurs ; en MP,interaction.guildest vide. Les commandes de serveur n'apparaissent de toute façon pas en MP. La méthodesetDMPermission()des anciens exemples est obsolète (deprecated) ; utilisez à la placesetContexts().- Par défaut, les types d'installation (integration types) d'une commande globale proviennent du réglage Installation du Developer Portal ; si User Install y est aussi activé, la commande est également proposée via l'installation utilisateur, là où le bot n'est pas présent.
setIntegrationTypes(ApplicationIntegrationType.GuildInstall)limite la commande à l'installation sur serveur. - La permission de la commande ne contrôle pas le salon cible ; la vérification
permissionsFor()empêche un membre d'envoyer, par l'intermédiaire du bot, une annonce dans un salon où il ne peut pas écrire lui-même. allowedMentions: { parse: [] }empêche les mentions@everyoneet les mentions de rôles contenues dans le texte de l'annonce d'envoyer des notifications.
8. Ajouter l'autocomplétion (autocomplete)
L'autocomplétion s'utilise pour les listes de plus de 25 éléments ou qui changent : le bot calcule la liste de suggestions au fur et à mesure que l'utilisateur tape. On ajoute setAutocomplete(true) à l'option et une fonction autocomplete au fichier de la commande ; le gestionnaire de l'étape 4 y transmet les requêtes. Elle ne peut pas être combinée avec addChoices() sur la même option ; si les deux sont écrits ensemble, une erreur RangeError se produit au chargement du fichier. commands/utility/faq.js :
const { MessageFlags, SlashCommandBuilder } = require('discord.js');
const FAQ = new Map([
['Inscription', 'Lisez le salon des règles et appuyez sur le bouton de validation.'],
['Obtenir un rôle', 'Choisissez votre rôle dans le menu du salon des rôles.'],
['Contacter le staff', "Ouvrez un ticket dans le salon d'assistance."],
]);
module.exports = {
data: new SlashCommandBuilder()
.setName('faq')
.setDescription('Répond à une question fréquente.')
.addStringOption((option) =>
option.setName('sujet').setDescription('Intitulé de la question').setRequired(true).setAutocomplete(true),
),
async autocomplete(interaction) {
const saisie = interaction.options.getFocused().toLocaleLowerCase('fr');
const resultats = [...FAQ.keys()]
.filter((sujet) => sujet.toLocaleLowerCase('fr').includes(saisie))
.slice(0, 25);
await interaction.respond(resultats.map((sujet) => ({ name: sujet, value: sujet })));
},
async execute(interaction) {
const sujet = interaction.options.getString('sujet');
if (!FAQ.has(sujet)) {
await interaction.reply({ content: "Ce sujet n'est pas dans la liste.", flags: MessageFlags.Ephemeral });
return;
}
await interaction.reply(`**${sujet} :** ${FAQ.get(sujet)}`);
},
};
getFocused()renvoie le texte que l'utilisateur est en train de taper ;respond()accepte au maximum 25 suggestions.- La réponse doit être donnée dans les 3 secondes et ne peut pas être différée ; si vous lisez les données dans une base de données, mettez-les en cache en mémoire.
- Les suggestions ne sont pas contraignantes : l'utilisateur peut aussi envoyer un texte absent de la liste ; c'est pourquoi
executevérifie de nouveau la valeur.toLocaleLowerCase('fr')met le texte en minuscules selon les règles de la langue française.
9. Enregistrer, tester et mettre à jour
Une fois les fichiers prêts, enregistrez les commandes et démarrez le bot :
npm run deploy
npm start
La sortie de l'enregistrement doit indiquer « 5 commandes enregistrées sur le serveur de test ». Sur le serveur de test, tapez / et essayez chaque commande, en laissant une option obligatoire vide et en saisissant une valeur hors limites. Pour les modifications suivantes :
| Modification | npm run deploy | Redémarrage du bot |
|---|---|---|
| Nouveau fichier de commande ajouté | Nécessaire | Nécessaire |
| Nom, description, option, permission ou contexte modifié | Nécessaire | Nécessaire |
Seul le code execute ou autocomplete a changé | Inutile | Nécessaire |
| Fichier de commande supprimé | Nécessaire | Nécessaire |
Une fois les commandes prêtes, passez à l'enregistrement global avec npm run deploy global, puis supprimez les copies du serveur de test avec npm run deploy vider ; sinon, les commandes apparaissent deux fois sur ce serveur.
Types d'options et limites de Discord
| Type | Méthode d'ajout | Méthode de lecture | Remarque |
|---|---|---|---|
| Texte | addStringOption | getString | Limite de longueur (0–6000), choix prédéfinis, autocomplétion |
| Entier | addIntegerOption | getInteger | Plage de valeurs, choix prédéfinis, autocomplétion |
| Nombre décimal | addNumberOption | getNumber | Comme l'entier ; accepte aussi les décimales |
| Oui/non | addBooleanOption | getBoolean | true / false |
| Utilisateur | addUserOption | getUser, getMember | getMember renvoie le membre du serveur |
| Salon | addChannelOption | getChannel | addChannelTypes permet de filtrer |
| Rôle | addRoleOption | getRole | Rôles du serveur |
| Utilisateur ou rôle | addMentionableOption | getMentionable | L'un ou l'autre |
| Fichier | addAttachmentOption | getAttachment | Fichier envoyé avec la commande |
Autres limites : 100 commandes slash globales par application, 100 commandes de serveur par serveur ; le total du nom, de la description et des valeurs d'une commande ne doit pas dépasser 8000 caractères. Les règles à jour figurent dans la documentation des commandes d'application de Discord, et le côté discord.js dans le guide discord.js.
Erreurs fréquentes
/ne propose pas la commande : l'enregistrement n'a pas été fait,GUILD_IDappartient à un autre serveur, ou l'application n'y est pas autorisée. Vérifiez le nombre de commandes dans la sortie de l'enregistrement et, si nécessaire, invitez de nouveau le bot ; si la liste n'est pas à jour, fermez puis rouvrez l'application Discord.- À l'enregistrement,
DiscordAPIError[50035]: Invalid Form Body: la définition ne respecte pas les règles de Discord ; la cause la plus fréquente, queSlashCommandBuilderne vérifie pas, est une option obligatoire écrite après une option facultative. Les noms avec majuscules ou espaces, ainsi que l'autocomplétion associée à des choix prédéfinis sur la même option, provoquent eux une erreur plus tôt, dès le chargement du fichier. - À l'enregistrement,
DiscordAPIError[50001]: Missing Access: l'application n'a pas été ajoutée au serveurGUILD_ID, ou les identifiants ont été confondus :CLIENT_IDdoit être l'Application ID etGUILD_IDl'identifiant du serveur. - La commande semble échouer et la console affiche
DiscordAPIError[10062]: Unknown interaction: la première réponse a dépassé 3 secondes ; appelezdeferReply()au début des tâches longues. InteractionAlreadyRepliedouDiscordAPIError[40060]: une deuxième réponse à l'interaction a été tentée. Après la première réponse, utilisezeditReply()oufollowUp(); n'exécutez pas le bot à deux endroits avec le même token./annoncerenvoie50001ou50013: le bot n'a pas la permission de voir le salon cible ou d'y envoyer des messages ; accordez ces permissions au rôle du bot dans les permissions du salon.
Questions fréquentes
Pourquoi utiliser des commandes slash plutôt que des commandes à préfixe (!) ?
Les commandes à préfixe lisent le texte des messages et exigent donc l'intent privilégié Message Content ; pour les bots qui doivent être vérifiés (100 serveurs et plus), cette autorisation est en outre soumise à approbation. Les commandes slash reçoivent les données via l'interaction, n'ont pas besoin de cette autorisation, et c'est Discord qui contrôle les paramètres.
Que faire si j'approche de la limite de 100 commandes ?
Regroupez les commandes similaires dans une seule commande avec des sous-commandes : addSubcommand() permet de définir des sous-commandes comme /role donner, /role retirer, et interaction.options.getSubcommand() renvoie celle qui a été choisie.
Faut-il réenregistrer les commandes après avoir déplacé le bot sur un VDS ?
Non. Les définitions sont conservées chez Discord ; il suffit de démarrer le bot sur la nouvelle machine avec le même token. Pour le faire tourner en continu, consultez le guide Garder un bot Discord en ligne 24 h/24, 7 j/7 sur un VDS.
Guides associés
- Comment créer un bot Discord à partir de zéro avec Discord.js v14
- Comment utiliser les boutons et les menus déroulants (select menu) dans Discord.js v14 ?
- Comment créer un système d'économie et de niveaux (level) avec Discord.js ?
- Garder un bot Discord en ligne 24 h/24, 7 j/7 sur un VDS : PM2, systemd et NSSM
Commentaires0
Pas encore de commentaire
Soyez le premier à partager votre avis.
Veuillez vous connecter ou vous inscrire pour laisser un commentaire.