Intents Gateway

Les Intents Gateway ont été introduits par Discord afin que les développeurs de bots puissent choisir quels événements leur bot reçoit en fonction des données dont il a besoin pour fonctionner. Les Intents sont des groupes nommés d'événements WebSocket prédéfinis, que le client discord.js recevra. Si vous omettez DirectMessageTyping, par exemple, vous ne recevrez plus les événements de saisie des messages directs. Si vous ne spécifiez pas les intents, discord.js génère une erreur.

Plutôt que d'activer aveuglément tous les intents, considérez les informations dont vous avez réellement besoin. Réduire le nombre d'événements inutiles que votre bot reçoit améliore les performances et réduit la bande passante et l'utilisation de la mémoire.

Intents Privilégiés

Discord définit certains intents comme "privilégiés" en raison de la nature sensible des données. Au moment de la rédaction de cet article, les intents privilégiés sont GuildPresences, MessageContent et GuildMembers. Si votre bot n'est pas vérifié et se trouve dans moins de 100 guildes, vous pouvez activer les intents de passerelle privilégiés dans le Portail des développeurs Discord sous "Intents de passerelle privilégiés" dans la section "Bot". Si votre bot est déjà vérifié ou est sur le point de nécessiter une vérification, vous devez demander des intents privilégiés. Vous pouvez le faire dans votre application de vérification ou en contactant l'équipe d'support Discord, en expliquant pourquoi vous avez besoin d'accès à chaque intent privilégié.

Avant de vous précipiter, vous devriez vous arrêter et réfléchir attentivement à la question de savoir si vous avez besoin de ces événements. Discord les a rendus opt-in pour que les utilisateurs de toute la plateforme puissent bénéficier d'un niveau de confidentialité plus élevé. Les présences peuvent exposer pas mal d'informations personnelles, notamment les jeux en cours de lecture et le temps en ligne global. Vous pourriez trouver qu'il n'est pas nécessaire pour votre bot d'avoir ce niveau d'informations sur tous les membres de la guilde à tout moment, considérant que vous obtenez toujours l'auteur de la commande en tant que GuildMember du message d'exécution de la commande et pouvez récupérer d'autres cibles séparément.

Erreur : Intents non autorisés

Si vous recevez une erreur préfixée par [DisallowedIntents], veuillez vérifier vos paramètres du tableau de bord de développement pour tous les intents privilégiés que vous utilisez. Consultez la documentation de l'API Discord pour des informations à jour.

Activation des Intents

Pour spécifier quels événements vous voulez que votre bot reçoive, d'abord réfléchissez à quels événements votre bot a besoin pour fonctionner. Ensuite, sélectionnez les intents requis et ajoutez-les à votre constructeur client, comme montré ci-dessous.

Vous pouvez trouver la liste de tous les intents de passerelle actuels et les événements appartenant à chacun sur la documentation de l'API Discord et les valeurs d'enum utilisées dans discord.js sur la documentation des types d'API Discord.

• Si vous avez besoin que votre bot reçoive des messages (MESSAGE_CREATE - "messageCreate" dans discord.js), vous devez utiliser les intents Guilds et GuildMessages, plus l'intent privilégié MessageContent pour recevoir les champs content, attachments, embeds et components du message.
• Si vous voulez que votre bot publie des messages de bienvenue pour les nouveaux membres (GUILD_MEMBER_ADD - "guildMemberAdd" dans discord.js), vous devez utiliser l'intent privilégié GuildMembers, et ainsi de suite.

const { Client, GatewayIntentBits } = require('discord.js');

const client = new Client({
	intents: [
		GatewayIntentBits.Guilds,
		GatewayIntentBits.GuildMessages,
		GatewayIntentBits.MessageContent,
		GatewayIntentBits.GuildMembers,
	],
});

Certaines méthodes qui semblent non reliées pourraient cesser de fonctionner si certains événements n'arrivent pas. Par exemple :

• L'intent Guilds remplit et maintient les caches guilds, channels et guild.roles, plus les événements liés aux threads.
  Si cet intent n'est pas activé, les données pour les interactions et les messages n'incluront que l'id de guilde et de canal, et ne se résoudront pas à la classe complète.
• L'intent GuildMembers maintient les membres de la guilde en cache à jour, y compris les changements dans leurs rôles et permissions, surnom, etc.
  Notez que vous recevez toujours des données complètes de membres avec les interactions et les messages sans cet intent activé.

Assurez-vous de fournir la liste des intents de passerelle et des partiels que vous utilisez dans votre constructeur Client lorsque vous demandez de l'aide sur notre serveur Discord ou référentiel GitHub.

Le champ Bits Intents

discord.js fournit la structure utilitaire IntentsBitField pour simplifier la modification des champs bits des intents.

Vous pouvez utiliser les méthodes .add() et .remove() pour ajouter ou supprimer des drapeaux (littéraux de chaîne Intents représentant un bit particulier) et modifier le champ de bits. Vous pouvez fournir des drapeaux individuels ainsi qu'un tableau ou un champ de bits. Pour utiliser un ensemble d'intents comme modèle, vous pouvez le passer au constructeur. Notez que le constructeur vide new IntentsBitField() crée une instance Intents vide, représentant aucun intent ou le champ de bits 0 :

const { Client, IntentsBitField } = require('discord.js');

const myIntents = new IntentsBitField();
myIntents.add(IntentsBitField.Flags.GuildPresences, IntentsBitField.Flags.GuildMembers);

const client = new Client({ intents: myIntents });

// autres exemples :
const otherIntents = new IntentsBitField([IntentsBitField.Flags.Guilds, IntentsBitField.Flags.DirectMessages]);
otherIntents.remove([IntentsBitField.Flags.DirectMessages]);

Si vous souhaitez afficher les drapeaux construits, vous pouvez utiliser les méthodes .toArray() et .serialize(). La première retourne un tableau de drapeaux représentés dans ce champ de bits, la deuxième un objet mappant toutes les valeurs de drapeaux possibles à un booléen, en fonction de leur représentation dans ce champ de bits.

Plus sur les champs de bits

Les Intents et les Permissions Discord sont stockés dans un entier de 53 bits et calculés en utilisant des opérations bitàbit. Si vous voulez approfondir ce qui se passe derrière les coulisses, consultez les articles Wikipedia et MDN sur le sujet.

Dans discord.js, les champs de bits Permissions et Intents sont représentés soit comme la valeur décimale dudit champ de bits, soit comme ses drapeaux référencés. Chaque position dans un champ de bits de permissions représente l'un de ces drapeaux et son état (soit référencé 1 soit non référencé 0).