Gateway Intents

[msciotti]

Hey all! This PR is going to be WIP for a bit while we finalize the intent system. I was asked to document this so that library developers and contributors could start work on supporting gateway intents.

The information in this PR is subject to change until finalized and merged, but the underlying system of how one specifies intents will not change with 99.9999999% certainty. We also will most likely not be changing the events within each intent barring any crucial feedback and requests, but we may add new intents, and still have the ability to shuffle events around if needed.

Long way of stating you can this this PR as documentation to start building out support, but be mindful of updates in case things change.

Rolleout timelines and deprecation periods are flexible, which is why dates have been left off in places. We want to make sure that people have time to update in a non-rushed way.

---

Intents are already working on the v6 gateway if you'd like to give them a try. If you are a library developer or contributor, I am also happy to whitelist a test bot for the GUILD_PRESENCES intent. Keep in mind the 100 guild restriction, so use a small/new bot for testing. DM me on Discord at Mason#1337 (you can find me in the DAPI server).

We will not be whitelisting everyone to try the GUILD_PRESENCES intent right now, as it's not necessary. We just want to make sure that libraries are updated accordingly.

---

Please feel free to use this issue to ask questions, or hit me up directly/in the Discord API server.

(Also please excuse any formatting errors or things I missed that we'll be cleaning up in the review process. If something is unclear, ask!)

---

Open Questions and Discussion

(For things we know people are talking about)

• We are currently already evaluating solutions for a "hacky" way to allow for user info updates separate from presence/activity updates. We know that most folks who use presence data do so because there's not another way to keep a store of user objects up to date. This is already being discussed internally :)

• Some of the events listed in the intents are new, like MESSAGE_REACTION_REMOVE_EMOJI. Anything here will be additionally documented if not already, and that can happen in this PR

• We are considering making similar whitelist requirements around the GUILD_MEMBERS intent. Comments about which start here. This may also allow us to send user updates in the GUILD_MEMBER_UPDATE event, hopefully letting more folks move of PRESENCE_UPDATES that rely on it only for keeping user info up to date.

PR Comment Edit Log

• Changed GATEWAY_PRESENCE, which doesn't exist, to GUILD_PRESENCES, which does :)

• Added info about new events listed in intents

• Comment in open questions about GUILD_MEMBERS intent

[cloudrac3r]

So to make sure I understand this correctly:

Currently:

• All bots, by default, receive all events
• Bots can opt out of PRESENCE_UPDATE by setting guild_subscriptions to false
• PRESENCE_UPDATE includes changes to nickname, online status, game played, and role list (and more).

In the future:

• All bots, by default, will receive all events except for PRESENCE_UPDATE
• Bots can opt in to receive PRESENCE_UPDATE by enabling it on the website, then providing it in intents
• Bots may only enable PRESENCE_UPDATE if they are in 100 guilds or fewer, but this restriction can be bypassed through some sort of whitelist system

Does this mean that bots without PRESENCE_UPDATE will not know their own role list, and will therefore not know if they have permissions to perform actions like sending a message, using embeds, or adding roles until they actually try that action?

Do we have any idea what this whitelist system entails? For what reasons could a bot's application be rejected?

[AnatoleAM]

@cloudrac3r You still get roles in standard guild member objects inside GUILD_CREATE payloads. Furthermore, changes to nickname are reflected in GUILD_MEMBER_UPDATE payloads.

[msciotti]

@cloudrac3r you've almost got it, yep! @amAnatole is correct that there are other ways to know about your bot's own roles.

As for the whitelist process, I'm currently working with folks on the policy. As with any policy that we write, I'm sure I am going to discover some fun edge case that we haven't explicit addressed :p But I promise the intent is not to trick people. I'll share more when I have more!

[MinnDevelopment]

The gateway seems to close the request with 4012: Invalid Intents if you specify a bitmask like 0xFFFFFFFF.

[kyranet]

I have a question regarding how the WS Opcode 8 (Request Guild Members).

When using presences: true (As documented in 12b414e) while the GUILD_PRESENCES intent is not enabled, what would be the behaviour this system would have? Would this bypass the intents system, return no presences, or cause a WS close?

[night]

@kyranet we are still figuring out how we want to handle deprecation on that. i can see a world where if you specify intents the opcode will ignore the parameter if you pass it and do not have the intent.

also for any library developers watching this thread we also are considering deeper changes to guild members with intents sooner than later (in light of recent abuse patterns we've been seeing). if we end up moving this direction members intent will have similar limitations + whitelist with this deprecation cycle too. if your library can already function with guild subscriptions turned off then it should support changes we may make to the guild members intent. we'll provide more details when we have something more solidified, but wanted to give a heads up.

[mikeshardmind]

we also are considering deeper changes to guild members with intents sooner than later (in light of recent abuse patterns we've been seeing). if we end up moving this direction members intent will have similar limitations + whitelist with this deprecation cycle too.

So bots won't have access to role info either without whitelisting if I'm understanding this? (member update is listed as part of the member intent, and contains role changes)

This would be a rather harsh and over the top restriction. Many bots utilize role info, whether to calculate the effective permissions a user should have or to determine if a user should be allowed to moderate another user.

[ghost]

Do I understand correctly that the implication of this is that you are going to be deprecating the guild_subscriptions field?

If so, I hope a new resource version is going to be released to prevent breaking existing bots that make use of that field.

[MinnDevelopment]

@nekokatt

While not deprecated, Guild Subscriptions have been superceded by Gateway Intents. You may continue to use guild subscriptions, but we recommend migrating to intents for even better results.

[Tropony]

We are currently already evaluating solutions for a "hacky" way to allow for user info updates separate from presence/activity updates

Does it even need to be hacky? It seems to me that such updates could easily be dispatched as GUiLD_MEMBER_UPDATE events which already contain a user object. In fact there doesn't seem to be anywhere in the docs that say an update to, e.g., a username or avatar won't be sent as GUILD_MEMBER_UPDATE, so bots written to the spec already ought to be prepared to get them there and shouldn't even need to be rewritten.

[ajloveslily14]

As a side effect(or maybe it was also intended) this stops the use of users being able to use curl and get a full list of members in a guild. Whether good or bad, it burdens people who insist on breaking TOS and using selfbots, so I guess that's always a plus?

[nmeyvis]

What is the criteria for being "whitelisted"?

[advaith1]

@nmeyvis you just need to show how your bot uses it

[Fyko]

When the 100 guild limit is in place for privileged intents, what will happen when someone tries to invite the bot and it's reached 100 servers? Will the user be stopped on the invite page with something somewhat like the private bot message?

[night]

Yes, the intention is the bot would not be able to be joined to additional guilds. We will have more information about the deprecation + verification processes soon™, so stay tuned.

[ziad8727]

Would bots over 100 guilds be temporarily banned from getting invited or will they get disconnected with a 4014?

[Taarek]

Seems very silly to disconnect an entire session because someone is trying to invite the bot.
If I had to guess, the inviter will just get a 400 with a message explaining why you were unable to invite the bot.

But as night mentioned we'll have more information soon

[ajloveslily14]

Honestly I do not see why any of this is needed. It just seems like unnecessary hassle that will cause more issues than solve

[guidez]

Honestly I do not see why any of this is needed. It just seems like unnecessary hassle that will cause more issues than solve

Multiple reasons were given in the thread.

[MattW-source]

@ajloveslily14

Aside from privileged intents, which I still don't quite understand. Gateway Intents as a whole are very useful. My bot gets sent a bunch of events that it doesn't need, it's a waste of bandwidth and CPU cycles. Gateway Intents allow you to toggle what events you want to receive, saving both you and Discord bandwidth and allowing a much more optimised infrastructure.

[ajloveslily14]

@MattIBM
I can understand things like not sending certain events, however what I don't understand is having "get list of guild members" being under this, because that only fires when requested so there's no reason to include it, right? Further more I've noticed that it's not just the gateway that it's implemented in as using just curl to get a list of members from a guild fails unless the intent is set. While it's not intended and breaks the TOS, user accounts can't use the /guilds//members endpoint anymore.

[Andre601]

If that 100 Guild limit would be in place for not whitelisted bots, would they just be unable to be invited into new Guilds, or would they even get removed from others?

[advaith1]

While it's not intended and breaks the TOS, user accounts can't use the /guilds//members endpoint anymore.
@ajloveslily14 That's probably an intentional change to stop spambots
and the /members change is documented, only a few http endpoints were restricted with Intents and it's to prevent bots from getting information of the members of a guild in any way unless they are approved.

If that 100 Guild limit would be in place for not whitelisted bots, would they just be unable to be invited into new Guilds, or would they even get removed from others?
@Andre601 I don't think they said anywhere that they will remove bots from servers; I assume that once they enable the whitelist, it'll automatically be disabled in the dev portal if the bot is on over 100 servers and you won't be able to connect unless you remove the intent.

[ajloveslily14]

I'm not sure how restricting the list of members contributes to spambots, something like dming everyone? It still doesn't solve the user token endpoint, but not intended so I guess I cant complain.

[advaith1]

yeah it prevents DMing everyone and also services like discool getting info on what servers users are in

[iiLunar]

What is intents? sorry im new to python.

[RedDaedalus]

This has nothing to do with Python – refer to the documentation for your library, or the gateway intent docs.