Discord intents : ce que c'est et comment les activer

Les Discord intents forment un système d'abonnement par lequel votre bot déclare à l'avance quels types d'événements il souhaite recevoir de la passerelle (gateway) Discord. Lors de sa première connexion, le bot dit « ces événements m'intéressent », et Discord ne lui envoie que ceux-là. Si vous n'activez pas les bons intents, votre bot ne fonctionnera pas du tout, ou bien certains événements (comme l'arrivée d'un nouveau membre ou le contenu d'un message) n'arriveront jamais. Dans cet article, j'explique ce que sont les intents, pourquoi les privileged intents sont différents, et comment les configurer correctement à la fois dans le Developer Portal et dans votre code.

Qu'est-ce qu'un intent et pourquoi existe-t-il ?

Un bot Discord reçoit des événements en temps réel via une connexion WebSocket persistante appelée la gateway : un message a été envoyé, un membre a rejoint, un salon a été mis à jour, une réaction a été ajoutée, et des dizaines d'autres. Sur les gros serveurs, ce trafic peut être énorme. Les intents permettent au bot de sélectionner les groupes d'événements qui l'intéressent réellement, réduisant à la fois la charge de Discord et la quantité de données que votre bot doit traiter.

Chaque intent correspond à un ensemble d'événements liés. Par exemple, l'intent Guilds couvre les événements de serveur, de salon et de rôle, tandis que l'intent GuildMessages couvre les événements de création/suppression de messages. Si vous n'activez pas un intent, les événements de ce groupe n'atteignent jamais votre bot et les écouteurs d'événements (event listeners) correspondants restent simplement silencieux.

Intents standard et privileged intents

Les intents se répartissent en deux catégories. La plupart sont standard et il suffit de les demander dans le code ; aucune approbation supplémentaire n'est nécessaire. En revanche, trois intents sont marqués comme privileged car ils donnent accès à des données sensibles :

• Server Members Intent (GuildMembers) : événements d'arrivée/départ de membres et liste complète des membres.
• Presence Intent (GuildPresences) : informations de présence comme le statut en ligne/hors ligne d'un utilisateur et le jeu auquel il joue.
• Message Content Intent (MessageContent) : le contenu texte réel, les pièces jointes et les embeds des messages.

Ces trois intents doivent être à la fois activés par un interrupteur dans le Developer Portal et demandés dans le code. Si vous demandez un privileged intent dans le code sans l'avoir activé dans le portail, le bot s'arrête avec une erreur Used disallowed intents lorsqu'il tente de se connecter.

Activer les privileged intents dans le Developer Portal

Pour activer les privileged intents, suivez ces étapes :

• Allez sur le Developer Portal de Discord et sélectionnez votre application.
• Ouvrez l'onglet Bot dans le menu de gauche.
• Trouvez les interrupteurs sous Privileged Gateway Intents : Presence Intent, Server Members Intent et Message Content Intent.
• Activez les intents dont votre bot a besoin et enregistrez avec Save Changes.

Une contrainte importante : si votre bot est présent sur plus de 100 serveurs, vous devez vérifier le bot et obtenir une approbation distincte pour chaque privileged intent avant de pouvoir l'utiliser. Les bots sous la barre des 100 serveurs peuvent les utiliser sans approbation. N'activez donc pas les privileged intents dont vous n'avez pas réellement besoin, car cela complique la montée en charge par la suite.

Définir les intents avec discord.js

Dans discord.js v14, les intents sont passés via l'énumération GatewayIntentBits lors de la création du Client. N'ajoutez que les intents dont vous avez besoin :

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

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

client.on('messageCreate', (message) => {
  if (message.author.bot) return;
  if (message.content === '!ping') {
    message.reply('Pong!');
  }
});

client.login(process.env.DISCORD_TOKEN);

Un piège classique à surveiller : si vous n'activez pas l'intent MessageContent, le champ message.content revient vide pour la plupart des messages. Votre bot semble ne pas répondre aux commandes, mais le vrai problème est qu'il ne voit jamais le texte du message. Les messages qui mentionnent le bot et les DM font exception à cette règle, mais pour les commandes à préfixe cet intent est indispensable.

Définir les intents avec discord.py

Côté Python, la logique est la même ; vous configurez un objet discord.Intents et le passez à Client ou commands.Bot :

import discord
from discord.ext import commands

intents = discord.Intents.default()
intents.message_content = True   # privileged
intents.members = True           # privileged

bot = commands.Bot(command_prefix='!', intents=intents)

@bot.event
async def on_ready():
    print(f'Connecté en tant que : {bot.user}')

bot.run('TOKEN')

Si nécessaire, vous pouvez tout activer avec discord.Intents.all(), mais c'est une mauvaise habitude : dès que vous demandez un privileged intent non activé dans le portail, le bot plante, et vous générez un trafic de données inutile. Suivez le principe du moindre privilège et n'activez que les intents que vous utilisez réellement.

Ne confondez pas intents et permissions

Une confusion fréquente consiste à considérer les intents comme la même chose que les permissions du serveur. Ce sont des couches différentes :

• Les intents déterminent quels événements le bot reçoit de la gateway ; ils sont définis au niveau de l'application.
• Les permissions déterminent ce que le bot peut faire dans un serveur ; elles sont accordées au niveau du rôle et du salon (envoyer des messages, gérer des salons, expulser des membres, etc.).

Par exemple, même avec l'intent GuildMembers activé, le bot ne peut pas expulser un membre sans la permission « Kick Members ». Inversement, même si vous donnez toutes les permissions au bot, il ne verra jamais les événements concernés si le bon intent n'est pas activé. Une configuration saine consiste à demander les intents nécessaires dans le code et à construire le lien d'invitation (URL OAuth2) avec uniquement le périmètre de permissions dont vous avez réellement besoin.

Questions fréquentes

Mon bot ne répond pas aux commandes et le contenu des messages est vide. Pourquoi ?

Le plus probable est que le Message Content Intent soit désactivé. Activez-le à la fois dans l'onglet Bot du Developer Portal et ajoutez l'intent MessageContent / message_content dans le code. Sans lui, les commandes à préfixe ne fonctionnent pas ; les commandes slash, en revanche, continuent de fonctionner sans l'intent de contenu.

J'obtiens une erreur « Used disallowed intents ».

Cette erreur signifie qu'un privileged intent demandé dans le code n'est pas activé dans le Developer Portal. Activez dans le portail l'intent nommé dans l'erreur et enregistrez, ou retirez-le de votre code si vous ne l'utilisez pas réellement.

Quels intents dois-je activer ?

Uniquement ceux dont la fonctionnalité de votre bot a besoin. Presque tous les bots ont besoin de l'intent Guilds. Ajoutez MessageContent pour les commandes à préfixe, GuildMembers pour les systèmes de bienvenue/au revoir, et GuildPresences pour le suivi de présence. Garder désactivés les privileged intents inutiles est préférable tant pour la sécurité que pour le processus de vérification au-delà de 100 serveurs.

Vous voulez configurer votre bot correctement, avec les bons intents et permissions ? Si vous avez besoin d'aide pour l'architecture d'un bot Discord, la configuration des intents et le déploiement, contactez-moi.