From 91ecd6560a71b1d81c38cbe28fe77aeb91dd7f9d Mon Sep 17 00:00:00 2001 From: Twentysix Date: Mon, 30 Aug 2021 23:41:41 +0200 Subject: [PATCH] [Docs] Add intents / public bots guide (#5221) * [Docs] Add intents / public bots guide * [Docs] Intent guide: update on d.py --- docs/bot_application_guide.rst | 3 +- docs/index.rst | 1 + docs/intents.rst | 137 +++++++++++++++++++++++++++++++++ 3 files changed, 140 insertions(+), 1 deletion(-) create mode 100644 docs/intents.rst diff --git a/docs/bot_application_guide.rst b/docs/bot_application_guide.rst index 0c9a17686..c3697083a 100644 --- a/docs/bot_application_guide.rst +++ b/docs/bot_application_guide.rst @@ -56,7 +56,7 @@ Continue to the next section to enable privileged intents. Enabling Privileged Intents ------------------------------- .. warning:: - Due to Discord API changes, Red Bot requires all intents. + :ref:`As explained in this page `, Red Bot requires all intents. \This section is required. 1. Make sure you're logged on to the `Discord website `_. @@ -75,5 +75,6 @@ Enabling Privileged Intents .. warning:: Red bots with over 100 servers require `bot verification `_ which is not covered in this guide. + Remember that as explained :ref:`here ` we do not support public bots. We encourage you to read that page before scaling up your bot. *Parts of this guide have been adapted from* `discord.py intro `_ *and* `discord.py privileged intents `_. diff --git a/docs/index.rst b/docs/index.rst index 564404bf6..65bc0d97c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -33,6 +33,7 @@ Welcome to Red - Discord Bot's documentation! :caption: User guides: getting_started + intents cog_guides/admin cog_guides/alias cog_guides/bank diff --git a/docs/intents.rst b/docs/intents.rst new file mode 100644 index 000000000..38b014d28 --- /dev/null +++ b/docs/intents.rst @@ -0,0 +1,137 @@ +.. _intents: +.. |br| raw:: html + +
+ +========================================== +About (privileged) intents and public bots +========================================== + +This page aims to explain Red's current intents requirements, +our stance regarding "public bots" and the impact of some announced +Discord changes coming in April 2022. + +To clarify: + +- **Small bots** are bots under 100 servers. They currently do not need to undergo Discord's + bot verification process +- **Public bots** (or big bots) are bots that have reached 100 servers. They need to be + `verified `_ + by Discord to join more than 100 servers and gain privileged intents + +.. 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. + +.. _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 `_ +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 ` +and our guidelines for the :ref:`verification process `. + +.. _intents-public-bots: + +----------- +Public bots +----------- + +Public bots, or big bots, are not our target audience and we **do not** offer support for them. + +Red was designed with one single goal in mind: a bot that you can host on your own hardware +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 +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. +Such Red instances *do exist*, 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. +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 +is *expected* that you know what's in your bot and how it works: that doesn't just mean on the +surface level, it means coding knowledge and the ability to maintain it on your own. + +.. _intents-bot-verification-process: + +------------------------ +Bot verification process +------------------------ + +When your bot ceases to be a small bot Discord will require you to verify your bot before allowing +it to join more servers and gain privileged intents. If you've read the previous section, +you will know that we do **not** support public bots. Logically, we also do not provide help for +the verification process. + +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. +They have installed their bot, some cogs, personalized it, yadda yadda. Again, they have been users, +not developers. 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 +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 +that the owner knows *on a technical level* what their bot does and how it works. And this is because outside +Red, the typical bot owner is also a developer who coded their own bot from scratch. + +While, again, we *cannot* support you going forward we want to give you some pointers to follow when filling +out your application: + +- Learn on a technical level what intents are and what's going on, under the hood, in your bot. Knowing its + features at a surface level is not enough. What features need intents to work and why? +- Forget that you're hosting Red. You're hosting *a bot* and Discord wants to know what *your bot* does and why + you're requesting privileged intents. |br| A **very bad** answer is: *"Because Red needs them"*. |br| + A **good** answer is: *"My bot has X features and it needs Y intents to work properly"*. |br| We've had a fair share + 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. + +.. _intents-slash-commands: + +--------------------------------- +Message intent and slash commands +--------------------------------- + +.. warning:: + + If you own a public bot it is extremely important that you read this section. + +Discord has announced that **starting April 2022** the content of users' messages +`will be "locked" behind message intent `_ |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 `_. |br| +But if you're the owner of a public bot, things might be a lot less pleasant. + +To recap, unless you have +message intent, you will only receive message content for: + +- Messages that your bot sends +- Messages that your bot receives in DM +- Messages in which your bot is mentioned + +In case it's not clear by now, your bot needs message content to parse (see) the commands it receives. And if +you don't attain message intent, your bot will not be able to... well, do anything. |br| +The *bandaid fix* is for you to change your bot's prefix to a mention and a good portion of your commands will likely +still work. You will however lose many functions, namely anything that relies on seeing message content to act. |br| +The more *proper fix* is also not easy. You will need to justify your need for the message intent to Discord and +they will only accept "compelling use cases". +`It is not known `_ +what those even entail 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 `_, which at the moment +are rather lacking in features and cannot cover all the functionalities that standard commands offer. |br| +Discord staff +`stated `_ +that they will want your bot to have slash commands when you ask for message intent. |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 `_, 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. \ No newline at end of file