Gateway Intents and Presence Data.md

Gateway Intents and Presence Data

Hey there!

My name is Mason; I’m a Product Manager at Discord, and I’m part of a new team here entirely focused on Bots, integrations, and the Discord API. You may have noticed a small bit of what we’ve done so far. We made some improvements to the Audit Log to include new events so bots don’t have to hit as many resources to do moderation actions, and we’ve been burning down API issue tracker requests as quickly as we can, fixing some long-standing bugs and implementing some new features. Today, I want to announce another long-awaited feature that we’re calling…Gateway Intents!

Gateway Intents

The Discord gateway can be spammy. Like, really spammy. For a long time, the dev community has asked us for a way to “subscribe” to only the gateway events their bots need, saving tons of computational cost. With the Gateway Intents system, you tell us on IDENTIFY what you’re planning to do—your "intents"—and we'll send you only the gateway events that you need.

Intents are a integer bit field specified on Identify payloads (intents: int), similar to permissions/flags.

List of Intents:

  GUILDS (1 <<< 0)
    - GUILD_CREATE
    - GUILD_DELETE
    - GUILD_ROLE_CREATE
    - GUILD_ROLE_UPDATE
    - GUILD_ROLE_DELETE
    - CHANNEL_CREATE
    - CHANNEL_UPDATE
    - CHANNEL_DELETE
    - CHANNEL_PINS_UPDATE

  GUILD MEMBERS (1 <<< 1)
    - GUILD_MEMBER_ADD
    - GUILD_MEMBER_UPDATE
    - GUILD_MEMBER_REMOVE

  GUILD_BANS (1 <<< 2)
    - GUILD_BAN_ADD
    - GUILD_BAN_REMOVE

  GUILD_EMOJIS (1 <<< 3)
    - GUILD_EMOJIS_UPDATE

  GUILD_INTEGRATIONS (1 <<< 4)
    - GUILD_INTEGRATIONS_UPDATE

  GUILD_WEBHOOKS (1 <<< 5)
    - WEBHOOKS_UPDATE

  GUILD_INVITES (1 <<< 6)
    - INVITE_CREATE
    - INVITE_DELETE

  GUILD_VOICE_STATES (1 <<< 7)
    - VOICE_STATE_UPDATE

  GUILD_PRESENCES (1 <<< 8)
    - PRESENCE_UPDATE

  GUILD_MESSAGES (1 <<< 9)
    - MESSAGE_CREATE
    - MESSAGE_UPDATE
    - MESSAGE_DELETE

  GUILD_MESSAGE_REACTIONS (1 <<< 10)
    - MESSAGE_REACTION_ADD
    - MESSAGE_REACTION_REMOVE
    - MESSAGE_REACTION_REMOVE_ALL
    - MESSAGE_REACTION_REMOVE_EMOJI

  GUILD_MESSAGE_TYPING (1 <<< 11)
    - TYPING_START

  DIRECT_MESSAGES (1 <<< 12)
    - CHANNEL_CREATE
    - MESSAGE_CREATE
    - MESSAGE_UPDATE
    - MESSAGE_DELETE

  DIRECT_MESSAGE_REACTIONS (1 <<< 13)
    - MESSAGE_REACTION_ADD
    - MESSAGE_REACTION_REMOVE
    - MESSAGE_REACTION_REMOVE_ALL
    - MESSAGE_REACTION_REMOVE_EMOJI

  DIRECT_MESSAGE_TYPING (1 <<< 14)
    - TYPING_START

Any event not specifically listed here is considered passthrough; you will always receive it

This means that if you’re running, say, a music bot, you can specify intents for voice_states and messages (to respond to commands) and never receive any other gateway events that would otherwise incur computational cost that you don’t want.

As part of the effort to help bots scale on Discord, we are also changing Presence Update events to be default OFF for all gateway subscribers when this change goes into effect. Most bots on Discord do not need the slew of user presence updates they get. They make up nearly 96% of events that bots receive, and they’re unnecessary spam for most bots. Enjoy getting your CPU cycles back!

When this system is put in place, the v6 Gateway will function mostly as before. Specifying intents will allow you to filter what you receive; not specifying intents will continue to give you the "firehose" of data. However, Presence Updates will be turned default OFF for Gateway v6 at the time of this change.

When we rev to v7 in the future, declaring intents will be required when connecting to the gateway.

Privacy

Discord cares deeply about the privacy of our users and the safety of applications on our platform. So, we're taking this opportunity to also make some changes in favor of data privacy.

We believe that some information on Discord is inherently sensitive, like the ability to know about a user's presence on Discord. Therefore, when these changes go live, there will be increased restrictions on Presence Update Gateway events:

• In order to receive Presence Update events at all, you must opt into the functionality for your bot in the Dev Portal
• You may operate unrestricted on Discord until you join 100 guilds
• At that point, you will no longer be allowed to join more guilds unless you either:
  • Turn off Presence Update receiving, or
  • Apply for scaled Presence Updates by:
    • Telling us what functionality your bot has that requires access to these events
    • Demonstrating that your bot actually has this functionality (a demo video)

Our goal in making this functionality application-based is to create a safer environment for the average Discord user. For those bots that do have a genuine need for this access, nothing will change for you once you apply. You'll get the data you need, and continue on you way!

For those bots that do not have functionality that requires this access, also nothing will change! In fact, with Gateway Intents, you'll see a wonderful reduction in CPU usage for quite literally no effort on your part.

Timing

We understand that this is a decent architectural change, and we want to give the appropriate amount of time for migration. Below is the timeline:

• <announcement_date>: Changes announced. 60 day migration period begins
• <announcement_date>: Applications for Presence Data open. Feel free to get it done early!
• <announcement_date + 60 days>: Changes are enacted
  • v6 Presence Update events are turned off by default and require whitelisting
  • You can now specify intents on IDENTIFY

Iconic