Skip to content

Discord GatewayIntents explained

Supercrafter100 edited this page Oct 30, 2023 · 15 revisions

Intents 101

Gateway Intents are probably one of the most misunderstood concepts of Discord bots. Though they are pretty fundamental to understand. Maybe not to it's full details but definitely to a point where you know when to use them and when not to.

Intents decide which events your Discord client will receive. They were created by Discord to limit the amount of events it should send to clients. Sending all events would cause a lot of data to be sent to a client that it might not need in the first place. With intents, developers can decide what they need and request the necessary intents accordingly.

You can find a list of the intent names and what events they receive here. Below is a quick example on how you should read that.

image If we look at the above image, the first intent is called Guilds. When you request that intent, you are telling the Discord api that you want to receive all events that are associated with that intent. In this case, that would mean you are getting all the events related to guilds (discord servers).

With discord.js, to get the correct name of the intent in the library, you should replace the _ with '' (emptiness) and make the next letter a capital one. This means that GUILD_MODERATION would become GuildModeration, GUILD_MESSAGES would become GuildMessages, etc.

In any case, only enable intents you strictly need. Don't request intents you don't require in the first place but put some thought in what you need.

How the intent number is calculated

The actual intents that are enabled are decided by looking at the number in binary. If there's a 1 it's enabled, if there's a 0 it's disabled! The decimal representation that we see is just an easy way for us to copy paste it and pass it along in requests and responses. As binary just isn't as readable to use as it is to programming languages.

Say we look at the intent number 1537. If we look at this number in binary using 2 bytes, we get the following: 0000000011000000001. Looking at the image earlier of the list of intents, we see that the GUILDS intent is in the 0th place (a 1 shifted to the left 0 times or 1 << 0). If we look at the number in the 0th place in our binary number (which is counted from right to left), we see that it's a 1! This means we are requesting the Guilds intent! We can also see that there is a 1 in the 9th and 10th place in our binary representation. If we look on the image above, we see that 1 << 9 corresponds to the GUILD_MESSAGES intent and 1 << 10 is the GUILD_MESSAGE_REACTIONS intent! So the documentation shows us at what position the intent bit is and we just have to set that to 0 or to enable or disable the intent. Neat stuff! This is also why the Discord.JS library calls them GatewayIntentBits because all it is is just modifying a bit in the number to 1 or 0!

If you want to know more about binary -> decimal conversions, see this coding challenge

If you want to know more about bitshifting, have a look at this coding challenge about bitshifting!

Privileged intents

Some intents are privileged. This means you explicitly have to enable them in your developer portal before you can request them. If you require access to a privileged intent and your Discord bot ends up needing to get verified. You need explicit approval from Discord to actually use those intents. You cannot just enable them and receive the events associated to the intent when you don't need it for your Discord bot to function.

Generally the rule of thumb regarding privileged intents is that if there's no other option to do something you want, you can use the intent. This is especially true for the MessageContent intent as Discord restricted it's access behind a pretty big verification process.

Why bitshifting in the first place? That's super complicated!

Bitshifting in this case is great for both performance and storage. You're only storing a single numerical value in your database while it corresponds to multiple boolean values. Bits are essentially just 0's and 1's which end up being true or false. Your processor is actually made to do these kind of bitshifting operations. So calculating these numbers is a SUPER fast process. This allows discord to use this at scale without any performance issues!

If you require more in-depth information about intents, you can use the following two resources:

Discord Developer portal: https://discord.com/developers/docs/topics/gateway#gateway-intents

DiscordJS Guide: https://discordjs.guide/popular-topics/intents.html#gateway-intents