Wat zijn Discord intents en hoe schakel je ze in

Discord intents vormen een abonnementssysteem waarmee je bot vooraf aangeeft welke soorten events hij van de Discord gateway wil ontvangen. Wanneer de bot voor het eerst verbindt, zegt hij "deze events interesseren me", en Discord stuurt alleen die. Schakel je niet de juiste intents in, dan werkt je bot ofwel helemaal niet, ofwel komen sommige events (zoals een nieuw lid dat erbij komt of de inhoud van een bericht) nooit binnen. In dit artikel leg ik uit wat intents zijn, waarom privileged intents anders zijn, en hoe je ze correct instelt, zowel in het Developer Portal als in je code.

Wat is een intent en waarom bestaat het?

Een Discord bot ontvangt realtime events over een blijvende WebSocket-verbinding die de gateway heet: een bericht is verstuurd, een lid is toegetreden, een kanaal is bijgewerkt, een reactie is toegevoegd, en tientallen andere. Op grote servers kan dit verkeer enorm zijn. Intents laten de bot de groepen events kiezen die hem echt aangaan, waardoor zowel de belasting van Discord als de hoeveelheid data die je bot moet verwerken afneemt.

Elke intent koppelt aan een bundel gerelateerde events. Zo dekt de Guilds intent server-, kanaal- en rol-events, terwijl de GuildMessages intent het aanmaken/verwijderen van berichten dekt. Schakel je een intent niet in, dan bereiken de events in die groep je bot nooit en blijven de bijbehorende event listeners simpelweg stil.

Standaard intents versus privileged intents

Intents vallen in twee categorieën. De meeste intents zijn standaard en je hoeft ze alleen in code aan te vragen; extra goedkeuring is niet nodig. Drie intents zijn echter gemarkeerd als privileged, omdat ze toegang geven tot gevoelige data:

• Server Members Intent (GuildMembers): events van leden die toetreden/vertrekken en de volledige ledenlijst.
• Presence Intent (GuildPresences): presence-informatie zoals de online/offline-status van een gebruiker en het spel dat hij speelt.
• Message Content Intent (MessageContent): de werkelijke tekstinhoud, bijlagen en embeds van berichten.

Deze drie moeten zowel met een schakelaar in het Developer Portal worden ingeschakeld als in code worden aangevraagd. Vraag je een privileged intent in code aan zonder hem in het portal te hebben ingeschakeld, dan stopt de bot bij het verbinden met een Used disallowed intents-fout.

Privileged intents inschakelen in het Developer Portal

Volg deze stappen om privileged intents in te schakelen:

• Ga naar het Discord Developer Portal en selecteer je applicatie.
• Open het tabblad Bot in het linkermenu.
• Zoek de schakelaars onder Privileged Gateway Intents: Presence Intent, Server Members Intent en Message Content Intent.
• Zet de intents aan die je bot nodig heeft en sla op met Save Changes.

Een belangrijke beperking: staat je bot in meer dan 100 servers, dan moet je de bot verifiëren en voor elke privileged intent afzonderlijk goedkeuring krijgen voordat je ze kunt gebruiken. Bots onder de 100 servers kunnen ze zonder goedkeuring gebruiken. Schakel daarom geen privileged intents in die je niet echt nodig hebt, want dat bemoeilijkt later het opschalen.

Intents definiëren in discord.js

In discord.js v14 worden intents doorgegeven via de GatewayIntentBits-enum bij het aanmaken van de Client. Voeg alleen de intents toe die je nodig hebt:

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);

Een klassieke valkuil om op te letten: schakel je de MessageContent intent niet in, dan komt het veld message.content voor de meeste berichten leeg terug. Je bot lijkt niet op commando's te reageren, maar het echte probleem is dat hij de berichttekst nooit ziet. Berichten die de bot vermelden en DM's zijn een uitzondering op deze regel, maar voor prefix-gebaseerde commando's is deze intent essentieel.

Intents definiëren in discord.py

Aan de Python-kant is de logica hetzelfde; je configureert een discord.Intents-object en geeft het door aan Client of 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'Ingelogd als: {bot.user}')

bot.run('TOKEN')

Als het nodig is, kun je alles inschakelen met discord.Intents.all(), maar dat is een slechte gewoonte: op het moment dat je een privileged intent aanvraagt die niet in het portal is ingeschakeld, crasht de bot en genereer je onnodig dataverkeer. Volg het principe van minimale rechten en schakel alleen de intents in die je echt gebruikt.

Verwar intents niet met permissies

Een veelvoorkomende verwarring is om intents te zien als hetzelfde als serverpermissies. Het zijn verschillende lagen:

• Intents bepalen welke events de bot van de gateway ontvangt; ze worden voor de hele applicatie gedefinieerd.
• Permissies bepalen wat de bot in een server mag doen; ze worden op rol- en kanaalniveau verleend (berichten sturen, kanalen beheren, leden kicken, enzovoort).

Zelfs met de GuildMembers intent ingeschakeld kan de bot bijvoorbeeld geen lid kicken zonder de "Kick Members"-permissie. Andersom: geef je de bot alle permissies, dan ziet hij de betreffende events nog steeds nooit als de juiste intent niet is ingeschakeld. Een gezonde bot-opzet betekent dat je de nodige intents in code aanvraagt en de uitnodigingslink (OAuth2-URL) bouwt met alleen de permissie-scope die je echt nodig hebt.

Veelgestelde vragen

Mijn bot reageert niet op commando's en de berichtinhoud is leeg. Waarom?

Hoogstwaarschijnlijk staat de Message Content Intent uit. Schakel hem in via het Bot-tabblad in het Developer Portal én voeg de MessageContent / message_content intent toe in code. Zonder die intent werken prefix-gebaseerde commando's niet; slash-commando's blijven echter werken zonder de content-intent.

Ik krijg een "Used disallowed intents"-fout.

Deze fout betekent dat een privileged intent die je in code aanvraagt niet is ingeschakeld in het Developer Portal. Schakel de in de fout genoemde intent in het portal in en sla op, of verwijder hem uit je code als je hem niet echt gebruikt.

Welke intents moet ik inschakelen?

Alleen die welke de functionaliteit van je bot vereist. Bijna elke bot heeft de Guilds intent nodig. Voeg MessageContent toe voor prefix-commando's, GuildMembers voor welkom/afscheid-systemen, en GuildPresences voor presence-tracking. Onnodige privileged intents uit laten is beter voor zowel de veiligheid als het verificatieproces boven de 100 servers.

Wil je je bot degelijk opzetten met de juiste intents en permissies? Heb je hulp nodig bij Discord bot-architectuur, intent-configuratie en deployment, neem dan contact met me op.