User Guide - shinyfinder/chatot-smogon GitHub Wiki

While the other pages in this wiki provide technical insight into the bot, this page is a guide for getting Chatot up and running in a Discord server.

Chatot is a Discord bot created for and managed by the Smogon community. The bot utilizes a hybrid approach to commands, offering users the ease of slash commands and, at times, the speed of prefix commands. If you've been around Discord for a while, you've probably come arcoss prefix commands, which are invoked by starting your message with some special character. Slash commands are all the rage nowadays, for various reasons, but they are invoked by starting your message with /. Discord already has a few built in if you'd like to try them out. Simply type / and you can scroll through the list of available commands. Once Chatot is added, its commands will show up here as well.

Before proceeding, enable developer mode within Discord. The primary thing this does is enable you to copy IDs from within the client. These IDs will likely be required at some point or another (espically the user ID, which you may need to ban someone who's not currently in the server, for example), so turn it on now before doing anything else. Seriously, please do it. Here's how:

In the bottom left corner of the client, click the gear icon to open your User Settings.

Scroll down a bit on the left sidebar and click Advanced. Then click the toggle to enable Developer Mode.

Your changes are automatically saved, so you may now click ESC in the upper right to return to chatting.

Swipe all the way to the left (finger moves left-to-right) until you can see the 4 tabs along the bottom. Click You.

In the upper right corner, click the cog to open your Settings.

Scroll down a bit until you find Advanced. Click it to open the Advanced settings.

Toggle the option to enable Developer Mode.

You may now click the back arrows in the upper left to go back to chatting.

You're now able to copy IDs! On desktop, right click on an object (user, message, server icon, channel, etc) and select the menu option to "Copy [object] ID."

On mobile, to grab the user's ID, open their profile by clicking on their profile picture. Then, press the 3 dots in the upper right corner to open a small menu. Select "Copy User ID." Nessage and channel IDs can be obtained by long pressing on the object to open the menu where you can choose to copy the ID. To get a server ID, long press the server icon then go to More Options. Scroll to the bottom and click "Copy Server ID."

In addition to making your life easier while using Chatot, you can now quickly link to a user's profile even if they aren't in the server. To do so enter <@id> into the chat, where 'id' is replaced with the ID you copied (you need the @ symbol still).

Chatot supports both guild (server) and User Application installation contexts. That means that by clicking Chatot's invite link or the Add App button on its profile, you are presented a choice of where to install it--either a server or your Discord account. Your choice determines where Chatot can be used, by whom, and which commands you will have available. Here is an invite link. Opening that link in a browser will present you with a prompt to add the bot to a server.

To invite Chatot to a server, you must have the "Manage Server" permission in that server. Click the invite link and choose "Add to Server." The invite link comes pre-set with some core permissions, but these can be modified at any time within Discord after the bot has joined. Authorize the bot to join the server you select in the next menu and it'll show up in the server's userlist. Alternatively, you can open the bot's user profile (left click on username, or right click > Profile) within Discord and click "+ Add App." Adding it to a server means full access to the list of commands, and anyone can use Chatot, subject to any permissions. By default, regular users only have access to a few commands, and as you go up the staff hierarchy, more commands are available to use (i.e. banning, logging, etc). Some commands are also available by DMing Chatot as you would a normal user. To use a command in a DM to Chatot, you must share a server with Chatot and have DMs enabled; having this permission disabled in your user settings will result in a error like "Unknown Integration" when you try to use a command in DMs.

To install Chatot to your personal Discord account, click the invite link or the "Add App" button on Chatot's profile and select the option to "Try It Now." This option allows you to use select commands anywhere on Discord, not just in servers that have added Chatot! Anywhere includes DMs with Chatot (even if you have DMs disabled), DMs with other users, and group DMs. Your usage of these commands in a server is subject to your permissions within the server. For example, you can't use a command in a channel where you don't have posting access. Further, if staff has disabled your ability to use the command (or any command), the command response within that server will only be visible to you. Meaning, you may still be able to use the command, but responses that would normally show up for everyone will only show up for you in servers where the command is disabled. If you wish, you can later revoke Chatot's link to your account by going to your Discord user settings > Authorized Apps. Chatot does not monitor regular messages or events in your DMs; it just replies to used slash command.

One quick side note: the wording on Discord is a bit confusing when you agree to add Chatot to your account. You're granting access for Chatot to DM you, not me. I suppose I'm vicariously DMing you via Chatot, but...yeah. Don't think too hard on it.

The rest of this guide assumes a full server installation.

Permissions for Chatot are two-fold: permissions for the bot itself, and permissions to use its commands.

As stated above, the invite link automatically grants the bot the permissions it needs to execute its commands. If you'd like to see why some of these permissions are needed, you can browse through the commands page. If at any time these need to be tweaked (i.e. you don't want it to do something, or the bot gets new features after having joined your server), you can do so from the Discord client. Upon joining, a new role is created for the bot (conveniently called Chatot). As with any other role, you can modify its permission set via Server Settings > Roles. You can also restrict access on a channel basis by modifying the channel permissions to include/exclude Chatot.

Remember to hoist the Chatot role (drag it further up the list) within the Roles menu to allow Chatot to effectively moderate members. Chatot can only moderate roles that are below it.

Command permissions work on an override system. Assuming you have the Manage Server permissions, you may tweak the bot's base permissions on the Server Settings > Integrations > click Manage next to Chatot screen. Henceforth, this screen will be referred to as Integrations > Chatot and is shown below.

By default, @everyone can use the commands everywhere. Overrides for these permissions can be set by clicking on the individual command from the Integrations > Chatot menu. The permissions set in the window that appears are applied on top of those set on the Integrations > Chatot page. Commands are coded with logical restrictions where possible. They can be viewed within Discord by clicking on the individual command. For example, the following screen appears when you click on the /ban command.

The informational alert in this screen indicates that members need a set of server permissions to use the command. By clicking View within this alert, you can see which ones. In the case here, /ban requires Ban Member permissions, as you'd expect. The required permissions for each command are detailed on the Commands page. This screen is also where you can set overrides for the command. Let's look at a few cases.

Taking the default settings as an example, on a bot-level (applies to every command), @everyone can use every command in every channel. The /ban command has a minimum permission set of Ban Members codded in. This means that anyone with the @everyone role (all members) and ability to ban members can use the /ban command in every channel. Let's say you don't want everyone to be able to use the bot by default, only members with the @botuser role. You can change this by disabling @everyone from the Integrations > Chatot menu and adding an override for the @botuser role (click the Add Roles or Members button then choose your desired role(s)). This setup is shown below.

In this configuration, only users with the @botuser role and the Ban Members permission can use /ban, because the permission overrides on the ban command are applied on top of those in the screen above. If the @botuser role has Ban Member permissions, then everyone with the role can use the command; however, if the role does not have Ban Member permissions, then no one with the @botuser role can use /ban (unless a user gains the required permission flag through another role) because the command by default only allows members with the Ban Members permission flag to use it.

Let's go back to the default example: @everyone, everywhere. Now, let's add the @botuser role to the /ban command itself rather than the bot integration. This setup is depicted in the following images.

In this setup, @everyone can use the bot, but the /ban command now has a role override to allow @botusers to use it. In this configuration, anyone with the @everyone role and the Ban Members permission OR the @botuser role can use /ban. It does not matter whether a user with the @botuser role has Ban Member permissions; anyone with that role can use the /ban command.

The same logic applies to channel overrides. To summarize, useage of the bot can be restricted to certain roles and channels within the Integrations > Chatot menu. These settings are applied to each command. Each command can be setup with certain overrides that work on top of these global settings and in many cases are coded with overrides, such as the /ban command requiring the Ban Members permission to use it. The overrides set for each command are independent of each other, meaning even though the command may require certain permissions to use by default, you can manually override them by granting access to additional roles or channels on the command itself. The 3 configurations described above are summarized in the table below.

Base Configuration	Command Base Permissions	Command Overrides	Who Can Use It
Default (@everyone/everywhere)	Ban Members	None	Members with Ban Members perm
@botuser (@everyone disabled)	Ban Members	None	Members with Ban Members perm and @botuser role
Default (@everyone/everywhere)	Ban Members	@botuser	Members with Ban Members perm or @botuser role

It is highly recommended that you use the "View Server as Role" feature under the Roles menu to ensure access is setup properly. Roles which do not access to the command on the permission level will not have it appear when you type / into the chat. Note that if you disallow @everyone from using the bot on the Integrations > Chatot menu, no one will be able to use any command; you will need to setup explicit exceptions for each command or provide a role for the base permissions. If you wish to remove a custom override that you applied, hover over the entry and click the trashcan that appears next to the checkmark/X toggle.

At this time, custom commands are usable by everyone and this cannot be configured. This is not to be confused with the /custom command, which is restrictable. /directory, /ping, /timestamp, and /wiki do not come with pre-coded restrictions, meaning everyone can use them by default.

Permitted location is trickier to test for. The client (Discord) only really takes into account whether they have permission to use the command, but it doesn't check for where they can use the command. A command can still show up in the menu if they have the base permissions to use it (i.e. Ban Members), even if they don't have the ability to use it within that specific channel....super lame, I know.

The benefit of location perms is that they're a little more straightforward to understand. If the All Channels option of the Integrations > Chatot menu is disabled, then people can't use Chatot commands anywhere in the server. So, you'll need to set channel overrides on the individual commands for where you want people to use them. And vice versa. If it's enabled at the top Integrations > Chatot menu, then people can use the commands in any channel they have access to. So if you want to turn some off, you'll need to set some denying overrides on the individual commands.

This is confusing, but as you play with it I'm sure it'll start to make sense.

Once you have the permissions setup, the hard part is done. Chatot comes with a varity of commands, the extent of when you can find on the commands page. Note that only commands marked with scope: global will be available to you when the bot first joins. If you want additional commands from the list, contact chaos and/or shiny finder.

To begin, type / in the chat. This will bring up a list of commands that you can use (only commands you have the permission to use will be shown to you). You can start typing and hit tab to complete the autocomplete. You'll likely find yourself using tab quite a bit to navigate through the fields. Want to see if it's working? Try /ping!

1. Enable developer mode within Discord
2. Click the invite link above
3. Choose to install to your account or a server. If a server...
4. Configure the permissions how you want them via Server Settings > Integrations > Manage (to the right of the bot app)
5. Ensure the bot is setup to effectively moderate members by dragging its role further up the Roles list
6. Use via /