└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # Discord Bots Best Practices 2 | *These guidelines are intended for public bots running on public guilds. If 3 | your bot is restricted to private guilds, this document most likely does not 4 | apply to you.* 5 | 6 | *If you have an idea for an addition or change to this document, please make a 7 | pull request and we can discuss it.* 8 | 9 | #### 1. Commands should be explicitly invoked. 10 | Bots should not be activated during a normal conversation. Instead, they should 11 | use a command prefix and/or respond when the bot is directly mentioned. 12 | 13 | #### 2. Use unique prefixes. 14 | Single-character prefixes, such as `!`, `$`, and `.`, are commonplace for activating 15 | commands and can overlap with other bots. Should you opt to use a prefix for your bot, 16 | consider using words (`owl`) or use unique Unicode characters (`"`). Avoid using `#`, 17 | `@`, `:`, or `/` as prefixes since they are used for Discord-specific actions like mentioning 18 | a user. Ideally, a bot's prefix should be configurable on a guild-by-guild basis so that 19 | a guild owner can ensure every bot has its own unique prefix. 20 | 21 | #### 3. Do not be greedy. 22 | Restrict yourself to a small number of prefixes, preferably one, to avoid the risk of 23 | colliding with others. 24 | 25 | #### 4. Do not overuse mentions. 26 | Try your best to avoid mentioning the user when replying to a command. Doing this can 27 | lead to bot reply loops. If a long-running command is executed, mentions are generally 28 | acceptable; however, private messages are preferred in this case. 29 | 30 | #### 5. Have an `info` command. 31 | Info commands should provide information about the bot, such as what framework it is 32 | using and its version. It should also include any `help` commands, and, most importantly, 33 | who made it. 34 | 35 | #### 6. Do not reply with an invalid command prompt. 36 | If a user attempts to use a command that does not exist, do not reply with anything. 37 | Let the command fail silently, and avoid things like "invalid command." If there is 38 | more than one bot in a server that shares a prefix, this can result in very obnoxious 39 | usage. Although, if the user ran a correct command but the arguments are wrong, then 40 | it is okay to reply with "invalid argument(s)." If your bot's prefix is configurable, 41 | this rule can be most likely be safely disregarded, however we still recommend following it. 42 | 43 | #### 7. Be respectful of Discord's API and Terms of Service. 44 | Bots that abuse and misuse the Discord API ruin things for everyone. Consider adding 45 | things like rate-limiting and backoff, and be intelligent about using the API. If you 46 | are unsure about the correct way to implement things, ask for help. Also, any bots that 47 | breach the Discord Terms of Service could result in both the bot's and the user's account 48 | to be terminated. ([Terms of Service](https://discordapp.com/terms) - [Developer / API Terms of Service](https://discordapp.com/developers/docs/legal)) 49 | 50 | #### 8. Ignore both your own and other bots' messages. 51 | This helps prevent infinite self-loops and potential security exploits. Using a zero 52 | width space such as `\u200B` and `\u180E` at the beginning of each message also prevents 53 | your bot from triggering other bots' commands. The Discord API also tells you if a user 54 | is a bot (`bot` property on `User` objects - 55 | [see the reference](https://discordapp.com/developers/docs/resources/user#user-object)). 56 | 57 | #### 9. Keep NSFW features in NSFW channels. 58 | All NSFW commands or features should only work in Discord's NSFW-marked channels. 59 | If these commands can be activated outside of these channels, it can cause your 60 | bot to quickly be banned as that is against the Discord Terms of Service. 61 | 62 | #### 10. Make usage clear to a new user. 63 | Allow users to mention the bot as an alternative to using prefixes ("@MyBot help"). 64 | This will help users who are new to your bot get started. Make sure that, however, 65 | places to ask for help can easily be found. One of the best ways to do this is using 66 | a bot's presence. Mentioning is truly the most unique prefix of all. 67 | 68 | #### 11. Escape mentions. 69 | Whenever a bot responds to anything, ensure that it escapes mentions 70 | (particularly `@everyone` and `@here`). While the user may not have permission to mention 71 | `@everyone`, your bot might, which can result in "mention injection." 72 | 73 | * **Note:** Some libraries do this automatically for you by default, but others will 74 | require you to set mentions to (not) parse. See the [Allowed Mentions](https://discordapp.com/developers/docs/resources/channel#allowed-mentions-object) section of Discord. 75 | --------------------------------------------------------------------------------