Discord Integration - kwsch/SysBot.NET GitHub Wiki

Discord integration requires configuration in the Hub for it to be functional in a server.

Setup

Create a new Discord Application and Bot for your server on Discord's Developer Portal.

Under the Bot tab, make your bot private to prevent other people from inviting it to their servers and using your Switch.

Under Privileged Gateway Intents, enable Presence Intent, Server Members Intent, and Message Content Intent under the same tab.
The Token can be obtained by clicking "Reset Token" on this page.

To invite the Bot to your server, you must generate an OAuth2 URL with the correct permissions. Click on the OAuth2 tab in the sidebar, click URL Generator, select bot under "Scopes," and grant your bot permissions. You will need only these permissions:

Manage Messages (deletes a user's message to hide their trade code, for privacy)
Send Messages
Read Message History
Attach Files (if convert is used to create a PKM file)
Embed Links (for the neat embeds such as in $stats)

Use the generated URL at the bottom to invite your bot to a server. Do not grant other permissions, especially admin; this is unsafe.

Again:
DO NOT GIVE YOUR BOT ADMINISTRATOR. IT WILL NOT FIX THE PROBLEM AND CAUSES MORE PROBLEMS.
DO NOT GIVE YOUR BOT ADMINISTRATOR. IT WILL NOT FIX THE PROBLEM AND CAUSES MORE PROBLEMS.
DO NOT GIVE YOUR BOT ADMINISTRATOR. IT WILL NOT FIX THE PROBLEM AND CAUSES MORE PROBLEMS.

Before Starting

Once you have added your Discord bot to your server, paste your Bot Token into the program's Hub config. Do not share the token or other people will be able to access your Discord bot account.

CLOSE THE PROGRAM AND OPEN IT AGAIN AFTER ADDING YOUR TOKEN TO THE CONFIG SETTINGS.

When you Start your bots via the GUI, the Discord bot will be launched.

Configure the bot's settings on your server. If you only want it in a few specific channels, remove all the permissions on the bot's role itself and add the role to specific channels only. Ensure that you do not have any other roles that are restricting the bot's permissions (including the "everyone" role), and you enter any extra codes needed if you have 2FA enabled.

NOTE: Restarting the program will not retain the users that have joined the queue.

Troubleshooting

I cannot see my bot user in my server.
Make sure that you are looking in a channel where it is not restricted. If it does not show up in Server Settings > Members, then you need to create a new invite URL and invite it.

The bot user in my server is always offline, even when I start the program.
There is something wrong with your token. Go into the Discord dev portal, click Reset Token, copy the Token into SysBot.NET, and then close/reopen the program. Make sure the Token is still visible under Integration > Discord > Token. Do not run multiple instances of the program out of the same folder -- they will overwrite each others' configs.

My bot user is online, but does not respond to commands.
Check the text logs in the logs folder where you have SysBot.exe.

If you do not see your commands in the logs, then your bot does not have permission to see the channel where you are typing, or it does not recognize you due to missing intents. Giving it permissions in the dev portal is not enough if you have overridden them in your server.
- Refer to the Guide on Setting Up Permissions to do this properly.
- You can remove all roles from the channel and allow the @everyone role to have all the required bot permissions to see if the bot responds. Then slowly add your restrictions back.
- Ensure that you have given it the correct intents (see the top of this page).
- View the server as your bot role to be sure you can see in the channel and write in it.
If you do see your commands in the logs, then your bot does not have permission to respond in the channel. Again, see the above for how to add permissions to write in a channel.
Under ChannelWhitelist, either whitelist the channels where you want the bot to have permission, or toggle AllowIfEmpty to true. You can use $addchannel in the channel to be added to have the program do this automatically.

My bot is not properly acknowledging users who have newly gained roles on Discord.
You do not have your intents set up correctly. Go back to the Setup section on this page to learn how to set the intents on your token.

Settings

Basic Settings

CommandPrefix: Used before all commands. Default is $. This can be set to multiple characters, e.g. $dp would change commands to $dptrade, $dpclone, etc.
ModuleBlacklist: Add the names of any modules you do not want loaded. Separate multiple module names with commas. A full list is available under $help.
BotGameStatus: Displays the status of the bot as the game it is playing.
HelloResponse: Customized response for $hi.
ReturnPKMs: If enabled, the bot will send users a PK8 in PMs when they interact with the trade bot functions.
BotColorStatusTradeOnly: If enabled, the bot's presence status on Discord will only be based on Trade-type bots.
ConvertPKMToShowdownSet: Toggles whether to reply with a Showdown Set whenever a PKM file is uploaded without a command.
ConvertPKMReplyAnyChannel: Toggles whether to reply with a Showdown Set in any channel the bot can see, not just whitelisted ones.
ReplyCannotUseCommandInChannel: If enabled, the bot will tell users when they cannot use a command. Otherwise, it will ignore them.
AsyncCommands: Toggle to handle commands asynchronously or synchronously. Can be left alone.

Role Settings

These settings grant permissions to specific roles on Discord. Roles are case-sensitive and must be entered exactly. Comment and ID fields are unused.

RoleCanTrade / RoleCanSeedCheck / RoleCanClone / RoleCanDump / RoleRemoteControl: Allow certain roles to use these bot commands. If AllowIfEmpty is set to true, then all users have that permission if no roles are specified.
RoleSudo: Gives a role admin powers over the bot. Should not be given out lightly as sudo users can cause damage by changing your bot configurations. Sudo users are treated like Favored Users.

User Settings

These settings grant permissions to specific users on Discord. To get a Discord user ID, you need to be in Developer Mode and right-click a user's name to "Copy ID". Comment and Name fields can be used for notes and do not affect function.

GlobalSudoList: List of user IDs that have admin powers over the bot in all servers, all channels, everywhere. Turn on AllowGlobalSudo to enable this.
- Users can be added with the $addsudo @user command or manually edited into the configuration.
- Users can be removed with the $removesudo @user.
UserBlacklist: List of Discord user IDs that cannot trade with the bot.
- Users can also be added with the $blacklist @user or $blacklistid # commands on Discord or manually added.
- Users can be removed with the $unblacklist @user and $unblacklistid #.
- A list of Discord users can be viewed with $blacklistsummary.
Trade > BannedIDs: List of Nintendo IDs that cannot trade with the bot. This does not use the Discord user ID.
- Refer to the Trade Abuse section for more details.

Channel Settings

These settings whitelist specific Discord channels by ID for commands and logging. Channel IDs can be obtained in Developer Mode, or a channel can be added with the appropriate command. Comment and Name fields can be used for notes and do not affect function.

ChannelWhitelist: list of channel IDs where the bot acknowledges commands.
- Channels can be whitelisted with $addchannel and removed with $removechannel.
- If AllowIfEmpty is set to true, then the bot will acknowledge all commands in channels it can see.
LoggingChannels: List of channel IDs where the bot posts its logs. If this is set to a public channel, users will be able to see link codes. Excessive logging will rate limit your bot for an hour. It is recommended to only use this feature if you are not at your PC and need to see what is happening.
- Logging channels can be added with $loghere and removed with $logclear or $logclearall.
TradeStartingChannels: List of channel IDs where the bot announces trades by ticket number. Use this if you want to inform users of where they are in the queue so they do not have to constantly spam $qs.
- Trade Starting channels can be added with $starthere and removed with $startclear or $startclearall.
EchoChannels: List of channel IDs where the bot announces status changes (e.g. start, stop, idle, queue opening/closing), result matches for EncounterBot, raid start status for RaidBot, and trade abuse detection.
- Echo channels can be added with $echohere and removed with $echoclear or $echolearall

Refer to the specific bot page or $help commands for more details.

When setting things up (prior to hitting Start for the first time), it is recommended that you close the program afterwards so that your settings are saved -- don't kill the process (if running under a debugger like Visual Studio).