Un embed Discord fait ce qu'un message en texte brut ne peut pas faire : il transforme l'information en une carte soignée, avec une barre latérale colorée, un titre, des champs, une vignette et un pied de page. Quand votre bot répond à une commande avec cette carte élégante plutôt qu'avec du texte brut, tout le monde sur le serveur trouve aussitôt le message plus lisible et plus professionnel. Dans ce guide, nous construisons pas à pas l'usage de la couleur, des champs et du thumbnail avec la classe EmbedBuilder de discord.js v14.
Qu'est-ce qu'un embed et quand l'utiliser ?
Un embed est un bloc structuré que Discord affiche à l'intérieur d'un message. La carte de prévisualisation qui apparaît automatiquement lorsque vous partagez un lien est aussi un embed ; les bots construisent simplement cette carte à la main. Là où les embeds sont utiles :
- Sorties de commande : des données qui se découpent en champs, comme un profil utilisateur, des statistiques de serveur ou la météo.
- Logs et notifications : utiliser la couleur pour signaler « succès / avertissement / erreur ».
- Annonces : des messages accrocheurs avec un titre, une description et une image.
Pour des réponses d'une seule ligne, un embed est superflu ; le texte brut se lit plus vite. Réservez l'embed aux cas où l'information gagne vraiment à être structurée.
Votre premier embed avec EmbedBuilder
Avec discord.js v14, les embeds se construisent via EmbedBuilder à l'aide de méthodes chaînées. Un exemple de base :
const { EmbedBuilder } = require('discord.js');
const embed = new EmbedBuilder()
.setColor(0x5865F2)
.setTitle('Infos du serveur')
.setDescription('Voici un résumé du serveur.')
.setTimestamp();
await interaction.reply({ embeds: [embed] });
Notez que l'embed est envoyé dans le tableau embeds du message, et non sous forme de chaîne brute. Un même message peut contenir jusqu'à 10 embeds, mais un seul suffit généralement.
La couleur : exprimez votre marque d'un seul ton
La couleur est la barre verticale sur le bord gauche de l'embed, et elle fixe le « ton » du message d'un coup d'œil. setColor accepte plusieurs formats :
const { Colors } = require('discord.js');
embed.setColor(0x57F287); // nombre hexa (vert)
embed.setColor('#ED4245'); // chaîne hexa (rouge)
embed.setColor([88, 101, 242]); // tableau RGB (blurple Discord)
embed.setColor(Colors.Gold); // constante de couleur intégrée
embed.setColor('Random'); // une couleur aléatoire à chaque fois
Une convention pratique : vert = succès, jaune = avertissement, rouge = erreur, blurple de marque = info neutre. Regrouper vos couleurs dans un seul objet garantit la cohérence :
const COLORS = { success: 0x57F287, warn: 0xFEE75C, error: 0xED4245 };
embed.setColor(COLORS.success);
Les champs : répartir les données en colonnes nettes
Les champs sont la partie la plus puissante d'un embed : chacun porte un name (titre) et une value (valeur). Avec inline: true, les champs s'alignent côte à côte ; Discord affiche au maximum trois champs inline par ligne.
embed.addFields(
{ name: 'Membres', value: '1 248', inline: true },
{ name: 'Salons', value: '37', inline: true },
{ name: 'Créé le', value: '12 mars 2021', inline: true },
{ name: 'À propos', value: 'Le serveur principal de la communauté.', inline: false },
);
Si vous voulez aligner les éléments avec une cellule vide, utilisez un titre invisible :
embed.addFields({ name: '', value: '', inline: true });
Le caractère ci-dessus est un espace de largeur nulle ; comme Discord refuse un name ou une value vide, c'est l'astuce que l'on utilise.
Thumbnail, image, auteur et pied de page
Les éléments restants complètent l'embed. Le thumbnail est la petite image carrée en haut à droite ; l'image est la grande illustration en bas. L'author affiche un petit titre avec une icône tout en haut, tandis que le footer propose une petite note tout en bas.
embed
.setAuthor({
name: 'Aslain Bot',
iconURL: 'https://example.com/bot.png',
url: 'https://aslain.dev',
})
.setThumbnail('https://example.com/avatar.png')
.setImage('https://example.com/banner.png')
.setFooter({ text: 'aslain.dev', iconURL: 'https://example.com/icon.png' });
Pour les images, vous pouvez utiliser une URL externe, ou référencer un fichier téléversé avec le bot via le schéma attachment:// :
const { AttachmentBuilder } = require('discord.js');
const file = new AttachmentBuilder('./avatar.png', { name: 'avatar.png' });
embed.setThumbnail('attachment://avatar.png');
await interaction.reply({ embeds: [embed], files: [file] });
Attention aux limites
Discord impose des limites strictes de caractères sur les embeds. Si vous les dépassez, l'API rejette le message et le bot échoue silencieusement. Les plus importantes :
- title : 256 caractères
- description : 4096 caractères
- nombre de champs : jusqu'à 25 (name 256, value 1024 caractères)
- footer.text : 2048, author.name : 256 caractères
- total cumulé de tout le texte d'un embed : 6000 caractères
Si vous insérez une saisie utilisateur dans un embed, sécurisez les valeurs en les tronquant avec, par exemple, slice(0, 1024) ; sinon, un message trop long peut casser toute la réponse.
Questions fréquentes
Pourquoi EmbedBuilder plutôt que MessageEmbed ?
Dans discord.js v13, la classe s'appelait MessageEmbed. La v14 l'a renommée EmbedBuilder et a supprimé addField (singulier) au profit de addFields (pluriel). Utilisez toujours les noms de la v14 dans les nouveaux projets ; copier des exemples plus anciens tels quels provoquera des erreurs.
Puis-je laisser les utilisateurs choisir la couleur de l'embed ?
Oui. Ajoutez une option à votre commande slash et passez la valeur hexa reçue à setColor. Validez simplement l'entrée d'abord : une valeur invalide lève une erreur, alors ajoutez un contrôle du type /^#?[0-9a-f]{6}$/i.
Les embeds s'affichent-ils de la même façon pour tout le monde ?
La structure est identique, mais il existe de petites différences visuelles entre les thèmes clair/sombre et mobile/bureau. Il est utile de tester sur mobile que les tailles de thumbnail et d'image ne débordent pas.
Vous voulez que les messages de votre bot soient à l'image de votre marque ? Du design des embeds à l'architecture des commandes, nous pouvons construire votre bot Discord ensemble. Contactez-moi pour parler de votre projet.