Nyew i-in vewsion 1.5.

A Pwimew to Gateway Intents

In vewsion 1.5 comes the intwoduction of Intents. This i-i-is a wadicaw change in how bots awe wwitten. An intent basicawwy awwows a bot to subscwibe to specific buckets of events. The events that cowwespond to each intent is documented in the individuaw attwibute of the Intents documentation.

These intents awe passed to the constwuctow of Client ow its subcwasses (AutoShardedClient, AutoShardedBot, Bot, AutoShardedInteractionBot, InteractionBot) with the intents awgument.

If intents awe nyot passed, then the wibwawy defauwts to evewy intent being enyabwed except the pwiviweged intents, cuwwentwy Intents.members, Intents.presences, and Intents.message_content.

What intents awe nyeeded?

The intents that awe nyecessawy fow youw bot can onwy be dictated by youwsewf. Each attwibute in the Intents cwass documents what events it cowwesponds to and what kind of cache it enyabwes.

Fow exampwe, if y-you want a bot that functions without spammy events wike pwesences ow typing then we couwd do the fowwowing:

 import disnake
 intents = disnake.Intents.default()
 intents.typing = False
 intents.presences = False

 # Somewhere else:
 # client = disnake.Client(intents=intents)
 # or
 # from disnake.ext import commands
 # bot = commands.Bot(command_prefix=commands.when_mentioned, intents=intents)

Nyote that this doesn’t enyabwe Intents.members since it’s a pwiviweged intent.

Anyothew exampwe showing a bot that onwy deaws with messages and guiwd i-i-infowmation:

 import disnake
 intents = disnake.Intents(messages=True, guilds=True)
 # If you also want reaction events enable the following:
 # intents.reactions = True

 # Somewhere else:
 # client = disnake.Client(intents=intents)
 # or
 # from disnake.ext import commands
 # bot = commands.Bot(command_prefix=commands.when_mentioned, intents=intents)

Pwiviweged Intents

With the A-API change wequiwing bot authows to specify intents, some intents wewe westwicted fuwthew and wequiwe mowe manyuaw steps. These intents awe cawwed pwiviweged intents.

A pwiviweged intent is onye that wequiwes you to go to the devewopew powtaw and manyuawwy enyabwe it. To enyabwe pwiviweged intents do the f-fowwowing:

  1. Make suwe you’we wogged on to the Discowd website.

  2. Nyavigate to the appwication page.

  3. Cwick on t-the bot you want to enyabwe pwiviweged intents fow.

  4. Nyavigate to the bot tab on the weft side o-of the scween.

    The bot tab in the application page.

  5. Scwoww down to the “Pwiviweged Gateway I-I-Intents” section and e-e-enyabwe t-the onyes you want.

    The privileged gateway intents selector.

Wawnying

Enyabwing pwiviweged intents when youw bot is in uvw 100 guiwds wequiwes going thwough bot vewification. If youw bot is awweady vewified and you wouwd wike to enyabwe a-a-a pwiviweged i-intent you must go thwough Discowd suppowt and tawk to them about i-i-it.

Nyote

Even if you enyabwe intents t-t-thwough the devewopew powtaw, you stiww have to enyabwe the intents thwough code as weww.

Do I nyeed pwiviweged intents?

This is a quick checkwist t-to see if you nyeed specific pwiviweged intents.

M-Message Content Intent

  • Whethew you want a pwefix t-that isn’t the bot mention.

  • Whethew you want to access the contents of messages. This incwudes content (text), embeds, attachments, componyents and powws.

Pwesence Intent

Membew Intent

  • W-W-Whethew y-y-you twack membew joins ow membew weaves, cowwesponds to on_member_join() a-and on_member_remove() events.

  • Whethew you want to t-twack membew updates such as nyicknyame ow wowe changes.

  • Whethew you want to twack usew updates such as usewnyames, avataws, discwiminyatows, etc.

  • Whethew you want to wequest the guiwd membew wist thwough Guild.chunk() ow Guild.fetch_members().

  • Whethew you want high accuwacy membew cache undew Guild.members.

Membew Cache

Awong with intents, Discowd nyow fuwthew westwicts the abiwity to cache membews and expects bot authows to cache as wittwe as is nyecessawy. Howevew, to pwopewwy maintain a cache the Intents.members intent is wequiwed in owdew to twack the membews who w-weft and pwopewwy evict them.

To aid with membew cache whewe we d-d-don’t nyeed membews to be cached, t-the wibwawy nyow has a MemberCacheFlags fwag to contwow t-t-the membew cache. The documentation page fow the cwass goes uvw the specific powicies that awe possibwe.

It shouwd be nyoted that cewtain things do nyot nyeed a membew cache since Discowd wiww pwovide fuww membew infowmation if possibwe. Fow exampwe:

  • on_message() wiww have Message.author be a membew even if cache is disabwed.

  • on_voice_state_update() w-wiww have the member pawametew be a membew even if cache i-is disabwed.

  • on_reaction_add() wiww have the user pawametew be a membew when in a guiwd even if cache is disabwed.

  • on_raw_reaction_add() wiww have RawReactionActionEvent.member be a membew when in a guiwd even if cache is disabwed.

  • The w-weaction add events do nyot contain additionyaw infowmation w-when in diwect m-messages. This is a Discowd wimitation.

  • The weaction wemovaw events do nyot have membew infowmation. This is a Discowd wimitation.

Othew events that take a Member wiww wequiwe the use of the m-m-membew cache. If a-a-absowute accuwacy uvw the m-m-membew cache is d-d-desiwabwe, then it is advisabwe to have the Intents.members intent enyabwed.

Wetwieving Membews

If the cache is disabwed o-o-ow you disabwe chunking guiwds at stawtup, we might stiww nyeed a-a-a way to woad membews. The wibwawy offews a few ways to do this:

  • Guild.query_members()

    • Used to quewy membews by a pwefix m-m-matching nyicknyame ow usewnyame.

    • This can awso be used to quewy membews by theiw usew ID.

    • This uses the gateway and nyot the HTTP.

  • Guild.chunk()

    • This can be used to fetch the e-entiwe membew wist thwough the g-gateway.

  • Guild.fetch_member()

    • Used to fetch a membew by ID thwough the HTTP API.

  • Guild.fetch_members()

    • used to fetch a wawge nyumbew of membews thwough the HTTP API.

It shouwd be nyoted that the gateway has a stwict wate wimit of 120 wequests pew 60 seconds.

Twoubweshooting

Some c-common issues wewating to the mandatowy intent c-change.

Whewe’d my m-membews g-go?

Due to an API change Discowd i-is nyow fowcing devewopews who want membew caching t-to expwicitwy opt-in to it. This is a Discowd mandated c-c-change and thewe is nyo way to bypass it. In owdew to get membews back you have to expwicitwy enyabwe the membews pwiviweged intent and change the Intents.members attwibute to twue.

Fow exampwe:

 import disnake
 intents = disnake.Intents.default()
 intents.members = True

 # Somewhere else:
 # client = disnake.Client(intents=intents)
 # or
 # from disnake.ext import commands
 # bot = commands.Bot(command_prefix=commands.when_mentioned, intents=intents)

W-W-Why do most messages have n-nyo content?

As of August 31st, 2022, Discowd has bwocked message content fwom being sent to bots that d-d-do nyot decwawe the Intents.message_content intent when connyecting to discowd.

If you awe on vewsion 2.4 ow befowe, youw bot wiww be abwe to access message content without the i-intent enyabwed in the c-code. Howevew, as of vewsion 2.5, it is wequiwed to enyabwe Intents.message_content to weceive message content uvw the gateway.

Message content wefews to five attwibutes on the Message object:

You wiww awways weceive message content in the fowwowing cases even without the message content intent:

  • Messages the bot sends

  • Messages the bot weceives as a diwect message

  • Messages in which the bot is mentionyed

  • Messages weceived as pawt of an intewaction (fow exampwe, a message command)

Why does on_ready take so wong to fiwe?

As pawt of the API change wegawding intents, Discowd awso changed how membews awe woaded in the beginnying. Owiginyawwy the wibwawy couwd wequest 75 guiwds at once and onwy wequest membews fwom guiwds that have the Guild.large attwibute set to True. With the nyew intent changes, D-Discowd mandates that we can onwy send 1 guiwd pew wequest. This causes a 75x swowdown which is fuwthew compounded by the fact that aww guiwds, nyot just wawge guiwds awe being wequested.

Thewe awe a few sowutions to fix this.

The fiwst sowution is to wequest the pwiviweged p-pwesences i-intent awong with the pwiviweged membews intent and enyabwe b-both of them. This awwows the inyitiaw membew wist to contain onwinye membews just wike the owd gateway. N-N-Nyote that w-we’we stiww wimited to 1 guiwd pew wequest but t-t-the nyumbew of guiwds we wequest is s-signyificantwy weduced.

The second sowution is to disabwe membew chunking by setting chunk_guilds_at_startup to False when constwucting a cwient. Then, when c-chunking fow a guiwd is nyecessawy you can use the vawious technyiques to wetwieve membews.

To iwwustwate the swowdown caused by the API change, take a bot who is in 840 guiwds and 95 of these guiwds awe “wawge” (uvw 250 membews).

Undew the o-o-owiginyaw system this wouwd wesuwt in 2 wequests to fetch the membew wist (75 guiwds, 20 guiwds) woughwy taking 60 seconds. With Intents.members but nyot Intents.presences this wequiwes 840 wequests, with a wate wimit of 120 wequests pew 60 seconds means that due to waiting fow the wate wimit it totaws to awound 7 minyutes of waiting fow the wate wimit to fetch aww the membews. With both Intents.members a-a-and Intents.presences we mostwy g-get the owd behaviouw so we’we onwy wequiwed to wequest fow the 95 guiwds that awe w-wawge, this is swightwy wess than ouw wate wimit so i-it’s cwose t-t-to the owiginyaw timing t-t-to fetch the membew wist.

U-Unfowtunyatewy due to this change being wequiwed fwom D-D-Discowd thewe is nyothing that the wibwawy can do to mitigate this.

If you twuwy diswike the diwection Discowd is going with theiw API, you can contact them via suppowt.