Discord gateway intents and the privileged three

Every gateway connection declares what it wants to hear about. That declaration is a bitfield of intents, and getting it wrong produces the most confusing class of bot bug there is: everything connects, nothing errors, and the data is empty.

The three privileged intents

Everything else is enabled by asking for it. These three are gated because each exposes something Discord treats as sensitive: who is in a server, what they are doing, and what they said.

The threshold that matters

An app with fewer than 10,000 users can turn all three on from the Developer Portal with no review. Past that, continued access goes through a request describing what the app does with the data. The number counts unique users across every server the app is in — which means a bot installed in a handful of very large communities crosses it long before a bot in hundreds of small ones. Operators who plan for “we’ll deal with it at a hundred servers” are measuring the wrong quantity.

MESSAGE_CONTENT is the odd one

The other two switch event families on and off. MESSAGE_CONTENT does something different: the bot still receives message events without it, but content, embeds, attachments, components and poll arrive empty. There are exemptions — messages that mention the bot, messages in DMs with it, and its own messages — which is precisely what makes the failure so hard to diagnose. A prefix-command bot appears to work when you test it by mentioning the bot, and does nothing when a real user types the prefix.

Diagnosing an intent problem

Three symptoms, one cause each:

• Empty message text from everyone except you — MESSAGE_CONTENT is off.
• The member cache never fills, and join events never fire — GUILD_MEMBERS is off.
• Everyone appears offline — GUILD_PRESENCES is off.

None of these raise an exception, because from the gateway’s point of view nothing went wrong: the bot asked for a narrower stream and got it. Intents are also fixed for the life of a session, sent in the identify payload, so enabling one in the portal changes nothing until the bot reconnects.