As of October 27th, 2020, a long-promised gateway update was rolled out to incorporate our gateway intents, and as a result, we've seen an escalation in bot connection issues and general confusion regarding the gateway rollout. As such, we wanted to take a moment to clarify some basic questions regarding the new gateway update and our privileged intents slate.
Please note that in this developer-oriented FAQ, the legacy term "guild" is used interchangeably with the modern term "server".
What's all this about, exactly?
As of October 27th, 2020 the events under the GUILD_PRESENCES and GUILD_MEMBERS intents will be turned off by default on all gateway versions. If you are using Gateway v6, you will receive those events if you have enabled the flags for those intents in the Developer Portal and have been verified if your bot is in 100 or more guilds. You do not need to use Intents on Gateway v6 to receive these events; you just need to enable the flags.
If you are using Gateway v8, Intents are mandatory and must be specified when connecting.
You can learn more about gateway versions in the Developer Documentation.
Why is my bot no longer working suddenly?
When the new gateway update was deployed, bots which weren't adequately prepared to specify gateway intents could have experienced a variety of issues. Common symptoms include:
- The bot not responding anymore, despite being online
- The bot cache being empty (only seeing a few users across all guilds)
- A library on ready event not firing or timing out (happening mostly on discord.py and discord.js bots but other libraries might exhibit the same behavior)
If you are affected by this, this is because of 2 gateway changes:
- You no longer have access to disabled privileged intents if you are not specifying intents
- You can no longer request member info for multiple guilds at the same time
Please note that a variety of libraries are facing other issues, including but not limited to lengthy startup times in JDA. You'll want to review the Community Resources page for links to various library homepages to learn more about potential impacts to your library.
How do I get back up and running?
Updating Your Library
First, you must make sure you're using a library version that can handle intents, and by extension no longer requests information on multiple guilds at once.
For discord.py, this means you need to update to v1.5 or higher.
For discord.js, this means you need to update to v12 or higher.
If you're unsure how to upgrade your bot to a new library release or are unclear regarding the intent compatibility of an alternative library, please see the library links provided in our Developer Community Resources.
Specifying Gateway Intents
Please note that a variety of our gateway intents are not privileged, meaning they do not require specific switches to be flipped or whitelisted access to be requested. You can review the entirety of our available intents here.
Specifying which intents you'd like to receive varies based on your chosen library. Documentation on how to specify gateway intents in discord.js is available here. Documentation for specifying gateway intents in discord.py is available here.
Please note that specifying intents requires discord.py v1.5 and higher or discord.js v12 and higher. For alternative libraries, please review our Community Resources.
Requesting Privileged Gateway Intents
Privileged gateway intents include GUILD_PRESENCES and GUILD_MEMBERS. The process of enabling access to these two intents depends on your bot's size, verification status, and the intent variety you need access to.
Unverified Bots in 75 Servers or Less
If your bot is in under 76 servers, and thus does not require or qualify for verification, you can enable access to either privileged intent by flipping the corresponding switch in your bot's Developer Portal prior to calling the intents in code.
Unverified Bots in 76 or More Servers
If your unverified bot is in 76 or more servers, you'll need to be verified prior to calling and using our privileged gateway intents. If you're not verified yet, we ask that you apply as soon as you can. You can request verification and whitelisting at the same time just by filling out the form in the Developer Portal.
Note that bots in 100 servers or more will need to be verified prior to continuing to join servers in addition to requesting intents.
Verified Bots
Once your bot is verified, you won't be able to manually flip the intent switches in the Developer Portal. To request whitelisted access to an additional privileged gateway intent for a verified bot, please send our support team a ticket here!
Make sure to include your bot's ID, which intents you're requesting, a basic description of your use case for the requested intent, and screenshots or video of that use case in action (or code snippets, if not user facing!).
There's more information on how to request intents over in the #verification-faq channel in our official Developers server, so please join the server if you've got additional questions!
Working with Limited Intents
In many situations, developers are granted access to one of the privileged intents, but not the other. Calling one without the other can be a bit different from library-to-library, but here's some general advice.
For bots that have the GUILD_MEMBERS intent and do not need or have the GUILD_PRESENCES intent
You can fill your bot cache again on startup by requesting the info for each guild individually. For details on how to do this please see the documentation of the library you use.
A Note On discord.js
If you're using discord.js, and you rely on building a cache of member data while only having access to partial intents, you should consider building a persistent cache which is updated when a member uses your bot, or by tracking member events using the GUILD_MEMBERS scope.
While discord.js does not currently fully support persistent caching, you could consider regularly triggering events to fetch all members and fill your cache as a stopgap.
For bots that do not have the GUILD_MEMBERS intent
If you do not need to do anything when a guild member joins, leaves, or is updated, you do NOT need the members intent. You cannot get a full member list to fill the cache, but in the majority of cases, a full member list is not necessary for building a persistent cache.
For finding users on a guild by ID or name, you can do this over the gateway without access to a privileged intent. Refer to the documentation of your library for information. The API also allows you to get this info by ID over the REST API.
For building basic leaderboards, we would instead encourage you to build a persistent database of user score information, and query that database to present active leaderboard data rather than querying a full member cache.
If you need further assistance on incorporating our guidance on intent usage, please visit the Developers server here!
Resources
There's a variety of resources that can help you navigate using gateway intents and requesting access to privileged intents. Here's a few!