Discord Gateway Intents Explained for Bot Developers

Gateway intents decide which events Discord sends to your bot. Choose too few and features silently stop working; choose too many and your bot wastes memory processing events it never uses — or can’t connect at all because it asked for something it isn’t allowed to have. This article explains how intents work and how to choose the right set.

What an intent is

When your bot connects to the gateway, it tells Discord which groups of events it wants. Each group is an intent. If you don’t request an intent, Discord never sends those events, and your library never sees them.

A few examples:

Intents are sent as a bitfield integer, but you never calculate it by hand — your library builds it from named flags.

Privileged intents

Three intents are privileged, because they expose more user data:

• Server Members (GuildMembers)
• Presence (GuildPresences)
• Message Content (MessageContent)

To use them you must enable them in the Discord Developer Portal under Bot → Privileged Gateway Intents, in addition to requesting them in code. If your code requests a privileged intent that isn’t enabled, the gateway closes the connection with close code 4014 (“disallowed intents”), and your bot never comes online. discord.js reports this as “Used disallowed intents”; discord.py raises PrivilegedIntentsRequired.

Verification changes the rules

Bots in fewer than 100 servers can toggle privileged intents freely. Once a bot reaches 100 servers, it must be verified by Discord, and verified bots need Discord’s approval for each privileged intent, with a justification for why the feature requires it. Plan for this before you grow: if you can build a feature without a privileged intent, you’ll have an easier path through verification.

Message Content: the one that trips people up

Without the Message Content intent, your bot still receives message events (with GuildMessages), but the content, embeds, attachments and components are empty for most messages. There are important exceptions — your bot does receive content for:

• messages that mention the bot,
• direct messages to the bot,
• messages the bot itself sent.

This is why modern bots use slash commands: interactions deliver their options directly and need no privileged intent at all. It’s also why a mention prefix (@YourBot help) keeps working without Message Content. If your bot relies on scanning every message — auto-moderation, keyword triggers — you’ll need the intent and, past 100 servers, approval.

Setting intents in code

discord.js v14

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

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.GuildMembers,     // privileged — enable in the portal
  ],
});

To receive DMs in discord.js, add GatewayIntentBits.DirectMessages and partials: [Partials.Channel], because DM channels aren’t cached until the first message arrives.

discord.py 2.x

intents = discord.Intents.default()   # everything except privileged intents
intents.members = True                # privileged — enable in the portal
# intents.message_content = True      # only if you really need it

bot = commands.Bot(command_prefix=commands.when_mentioned, intents=intents)

Intents.default() is a good starting point: it enables all non-privileged intents. For the leanest bot, start from Intents.none() and enable only what you use.

JDA 5

JDABuilder.createLight(token, GatewayIntent.GUILD_MESSAGES, GatewayIntent.GUILD_MEMBERS) — JDA also asks you to configure matching cache flags, and warns if a cache flag needs an intent you didn’t request.

Intents and memory

Every intent means more events to receive, parse and often cache. The effect is small for most intents, but two stand out:

• GuildPresences is by far the heaviest. In large servers, presence updates arrive constantly — every status change of every online member. Requesting it can multiply CPU and memory use. If you don’t display or react to presences, don’t request it.
• GuildMembers lets your library cache members as they’re seen and fetch member lists. In big servers, member caches grow large. Limit member caching if you only need join and leave events.

Dropping unused intents is often the easiest memory win available. See how much RAM a Discord bot needs and reducing memory usage in discord.js bots.

Choosing the minimum set

Work backwards from your features:

1. Slash commands only? Guilds is usually enough.
2. Welcome messages or autoroles? Add GuildMembers (privileged).
3. Logging message edits and deletes? Add GuildMessages. You’ll need MessageContent to log what was said.
4. Reaction roles? Add GuildMessageReactions.
5. Music? Add GuildVoiceStates.
6. Status-based features? Only then add GuildPresences.

Write the reason for each intent in a comment next to it. When you apply for verification, you’ll have your justifications ready.

Troubleshooting intent problems

Bot won’t connect, close code 4014. A privileged intent is requested in code but not enabled in the portal. Enable it, or remove it from code.

Events never fire. The matching intent isn’t requested. guildMemberAdd needs GuildMembers; messageCreate in servers needs GuildMessages.

Messages arrive with empty content. You’re missing MessageContent, and the message doesn’t mention the bot. Switch the feature to slash commands, or enable the intent.

DM handler never runs in discord.js. Add DirectMessages and Partials.Channel.

Memory is high in large servers. Check for GuildPresences you don’t need, and limit member caching.

Summary

Intents choose which events your bot receives. Three are privileged — Server Members, Presence and Message Content — and must be enabled in the Developer Portal, with Discord’s approval once your bot is verified at 100 servers. Request the smallest set your features need, prefer slash commands over reading message content, avoid the presence intent unless you truly use it, and document why each intent is there.