CopyBot/Red-DiscordBot
1
0
Fork 0
mirror of https://github.com/Cog-Creators/Red-DiscordBot.git synced 2025-11-06 03:08:55 -05:00
Code Issues Packages Projects Releases Wiki Activity

Rewrite intents and public bots doc page (#6578)

Browse Source
This commit is contained in:
Michael Oliveira 2025-08-17 13:06:25 -04:00 committed by GitHub
parent 3fd23d4163
commit ec66666036
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 42 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
docs/intents.rst
View File

@ -8,40 +8,20 @@ About (privileged) intents and public bots
========================================== ==========================================
This page aims to explain Red's current intents requirements, This page aims to explain Red's current intents requirements,
our stance regarding "public bots" and the impact of some announced our stance regarding "public bots", and the discord bot verification process.
Discord changes coming in April 2022.
To clarify: To clarify:
- **Small bots** are bots under 100 servers. They currently do not need to undergo Discord's - **Small bots** are bots under 100 servers. They currently do not need to undergo Discord's
bot verification process bot verification process
- **Public bots** (or big bots) are bots that have reached 100 servers. They need to be - **Public bots** (or big bots) are bots that have reached 100 servers. They need to be
`verified <https://support.discord.com/hc/en-us/articles/360040720412-Bot-Verification-and-Data-Whitelisting>`_ `verified <https://support-dev.discord.com/hc/en-us/articles/23926564536471-How-Do-I-Get-My-App-Verified>`_
by Discord to join more than 100 servers and gain privileged intents by Discord to join more than 100 servers and gain privileged intents
.. warning:: .. warning::
It is **very** important that you fully read this page if you're the owner of a public bot or strive to scale your bot at that level. It is **very** important that you fully read this page if you're the owner of a public bot or strive to scale your bot at that level.
.. _intents-intents:
-------
Intents
-------
Red currently requires **all intents** to be active in order to function properly.
The reason for this requirement is that there are some technical challenges that need
to be overcome before we're able to adapt Red to function with only *some* intents:
these challenges are mainly due to the modular / extensible nature of Red and the fact
that Red has a long history (dating back to 2016!), making big changes naturally slower
to happen. In comparison, intents have been introduced fairly recently. |br|
This is not a problem if you have a small bot: you can simply go to the
`Discord development portal <https://discord.com/developers/applications/me>`_
and enable them. However, if you have a public bot Discord will want you to attain
verified status: you should read :ref:`our stance regarding public bots <intents-public-bots>`
and our guidelines for the :ref:`verification process <intents-bot-verification-process>`.
.. _intents-public-bots: .. _intents-public-bots:
----------- -----------
@ -54,8 +34,10 @@ Red was designed with one single goal in mind: a bot that you can host on your o
and customize to your needs, making it really *your* bot. **The target audience of Red are server and customize to your needs, making it really *your* bot. **The target audience of Red are server
owners with a few servers**, often with specific needs that can be covered by the vast cog ecosystem owners with a few servers**, often with specific needs that can be covered by the vast cog ecosystem
that the community has built over the years. |br| Red was never built with big bots in mind, that the community has built over the years. |br| Red was never built with big bots in mind,
bots with thousands upon thousands of servers: these bots face unique challenges. bots with thousands upon thousands of servers: these bots face unique challenges. Large bots need
Such Red instances *do exist*, it is not impossible to adapt Red and meet those criteria, to be extremely efficient to handle the large amount of requests they receive, and often need to
distribute this work across multiple processes or machines to keep up.
Such Red instances *do exist*, and it is not impossible to adapt Red and meet those criteria,
but it requires work and bot owners with the technical knowledge to make it happen. but it requires work and bot owners with the technical knowledge to make it happen.
It is **not** something that we support. |br| It is **not** something that we support. |br|
When your bot reaches the public bot scale and it is therefore required to be verified it When your bot reaches the public bot scale and it is therefore required to be verified it
@ -75,8 +57,8 @@ the verification process.
Regardless of our stance, we do feel the need to give some pointers: many bot owners reach this point Regardless of our stance, we do feel the need to give some pointers: many bot owners reach this point
and become fairly lost, as they've simply been *users* so far. and become fairly lost, as they've simply been *users* so far.
They have installed their bot, some cogs, personalized it, yadda yadda. Again, they have been users, They have installed their bot, some cogs, personalized it, but have not needed to write any code.
not developers. Unless they also have an interest in development, they will likely not have a clue about Unless they also have an interest in development, they will likely not have a clue about
what's going under the hood, much like you're not expected to be a mechanic to drive your car. And there's what's going under the hood, much like you're not expected to be a mechanic to drive your car. And there's
nothing wrong with that! Red has been designed to be as user friendly as possible. |br| nothing wrong with that! Red has been designed to be as user friendly as possible. |br|
The problem is this: Red is an outlier. Discord has built the bot verification process with the expectation The problem is this: Red is an outlier. Discord has built the bot verification process with the expectation
@ -94,41 +76,44 @@ out your application:
of people that in their naivety went with the bad answer and it seems that at this point merely mentioning Red of people that in their naivety went with the bad answer and it seems that at this point merely mentioning Red
is a guaranteed way to have your application rejected. is a guaranteed way to have your application rejected.
.. _intents-slash-commands: .. _intents-intents:
--------------------------------- -------
Message intent and slash commands Intents
--------------------------------- -------
.. warning:: Red expects **all intents** to be active. It is possible, but not recommended, to disable
specific intents using the ``--disable-intent`` flag. If an intent is missing, you may
experience errors due to Red expecting information provided by the intent to be present.
If you own a public bot it is extremely important that you read this section. Discord currently considers 3 intents to be
`privileged <https://support-dev.discord.com/hc/en-us/articles/6205754771351-How-do-I-get-Privileged-Intents-for-my-bot>`_,
and requires large bots to additionally apply for access to these intents. **If you have a small
bot**, you can simply follow :ref:`these instructions <enabling-privileged-intents>` to enable them.
Discord has announced that **starting April 2022** the content of users' messages A breakdown of how privileged intents are used in Red is provided below.
`will be "locked" behind message intent <https://support-dev.discord.com/hc/en-us/articles/4404772028055>`_ |br|
If you're the owner of a small bot, fear not, this is yet another box that you have to tick from the
`Discord development portal <https://discord.com/developers/applications/me>`_. |br|
But if you're the owner of a public bot, things might be a lot less pleasant.
To recap, unless you have The **Message Content** intent is required to use text based commands and inputs for
message intent, you will only receive message content for: configuration and all built in functionality. App commands (also known as slash commands)
are limited to a total of 100 top level commands, which is difficult to manage on
a modular bot. The approach we have taken to address this issue is to allow 3rd party
cogs to provide slash commands, but require bot owners to pick which slash commands
they actually want to use with the ``[p]slash`` command.
Under this system, bot management commands that are not exposed to users are still
expected to be provided as text commands, which requires the bot to be able to access
message content. There are no current plans to provide slash versions of core commands.
- Messages that your bot sends .. note::
- Messages that your bot receives in DM It is possible to work around this intent by using the ``--mentionable``
- Messages in which your bot is mentioned flag, and using the bot mention as a prefix to use text based commands.
In case it's not clear by now, your bot needs message content to parse (see) the commands it receives. And if The **Guild Members** intent is required to properly cache member information, including
you don't attain message intent, your bot will not be able to... well, do anything. |br| what users are in each server, what roles they have, what their name is, etc. It is also
The *bandaid fix* is for you to change your bot's prefix to a mention and a good portion of your commands will likely required to receive events corresponding to when members join or leave a server, and when
still work. You will however lose many functions, namely anything that relies on seeing message content to act. |br| they change their nickname or other server options. Almost all cogs expect to be able
The more *proper fix* is also not easy. You will need to justify your need for the message intent to Discord and to reference the member cache in order to avoid making API requests, and are not set
they will only accept "compelling use cases". up to check if the intent is present before doing so.
`It is not known what those even entail <https://gist.github.com/spiralw/091714718718379b6efcdbcaf807a024#q-what-usecases-will-be-valid>`_ at this point, but they have already stated that "parsing commands" is not a valid justification. |br|
To make the matter worse, Discord is making `a huge push for all bot developers to implement slash commands <https://support.discord.com/hc/en-us/articles/1500000368501-Slash-Commands-FAQ>`_, which at the moment The **Guild Presences** intent is required to view the activities and status of
are rather lacking in features and cannot cover all the functionalities that standard commands offer. |br| users. Cogs which perform actions on users based on their activity or status will
Discord staff be unable to access this information if this intent is not enabled.
`stated that they will want your bot to have slash commands when you ask for message intent <https://gist.github.com/spiralw/091714718718379b6efcdbcaf807a024#q-if-we-are-granted-this-intent-will-bots-be-sanctioned-if-they-use-it-for-their-own-use-case-but-also-to-continue-to-run-normal-non-slash-commands-or-do-we-assume-that-if-you-are-granted-the-intent-you-are-trusted-with-it-and-are-allowed-to-use-it-for-additional-uses>`_. |br|
Slash commands might very well turn out to be a big undertaking for the Red team to implement, even more now that our
underlying library, `discord.py <https://github.com/Rapptz/discord.py>`_, has been discontinued. |br|
The time window that Discord is giving us to adapt is very narrow: **Red will likely not be able to support slash
commands for April 2022** and you should plan accordingly.