Skip to content

Latest commit

 

History

History
159 lines (123 loc) · 10 KB

README.md

File metadata and controls

159 lines (123 loc) · 10 KB
Raw

ModMail - Discord Bot

Simple ModMail Discord bot designed for a small server and people that want to maintain their own ModMail bot in discord. ModMail is a bot that create a private space between moderator and user to address an issue by acting as a bridge between user DM channel and new temporary channel inside a thread server.

Disclaimer

This bot only support one pair of server per bot, one main server and one thread server. I'm debugging the bot alone so expect some bugs passed to GitHub, and if you encounter bugs report here.

Notes

This is a complete rewrite of previous version. This version of the bot use Replit nix to meet node version requirement for Discord.Js v13 to host it in Replit and it's still in beta version. This bot use slash command and currently can't receive file attachment as an input due Discord API limitation. It's still a planned feature for slash command option as stated in this link. Global slash commands need up to an hour to register properly.

Requirements

  • Node.js v16.6.0 or higher
  • Npm v7.0.0 or higher

Installation

I. Setting up the bot

  1. Create a discord bot.
  2. While still in discord developer page, scroll down to Privileged Gateway Intents section and turn on Server Members Intent.
  3. Invite the bot to your server with following scopes and permissions.
    • Required scopes: bot, application.commands.
    • Required permissions: Manage Roles, Manage Channels, Read Messages/View Channels, Send Messages, Embed Links, Attach Files, Read Message History, Mention Everyone

If you don't understand Discord permissions rules, either give the bot Administrator permission or read this guide.

You'll need to re-invite the bot with correct scopes if you get "Missing Access" error.

II. Preparing the source code

  1. Download latest source code here and extract it.
  2. Copy your bot token from discord developer page.
  3. Open .env file and paste your bot token right after the equal sign on TOKEN= and save the file. e.g. TOKEN=YourBotTokenHere
  4. Copy your discord User ID.
  5. Open defaultConfig.json file and paste your discord user id inside double quotes "" character that are after "ownerID": and save the file. e.g. "ownerID": "YourUserIdHere"

Setting ownerID is recommend since it'll limit who can use critical commands.

III. A. Replit

We can't host on Replit for free now, read https://blog.replit.com/hosting-changes for more information.

  1. Create Replit account and login.
  2. Click + Create Repl button.
  3. Choose Nix (beta) as template, and then click + Create Repl.
  4. Go to your source code folder and select all the files.
  5. Drag and drop them to Files pane on Replit and click replace.
  6. Go to Replit shell (ctrl+shift+s) and run npm install command.
  7. If the installation finished without any error, click Run button at the top of Replit page and your bot should be online.

III. B. Non Replit User

ReplDB show an error when used outside Replit. Follow this instruction to change the database.

  1. Open DB.js file from functions folder, comment ReplDB section and uncomment Sequelize section.
  2. Delete or rename current package.json file.
  3. Rename sequelize-package.json file to package.json.
  4. Open terminal from the main folder and run npm install command.
  5. If the installation finished without any error, run npm start command from the terminal.

IV. Setting up the bot

  1. Prepare the following stuff before proceed:
    • Main Server : Server that are moderated by moderator. The bot need to be inside the server too.
    • Thread Server : Server where thread channels will be created. The bot need to be inside the server too.
    • Category Channel : Category channel that will hold thread channels. Need to be inside Thread Server.
    • Log Channel : Channel where thread logs will be sent. Need to be inside Thread Server.
    • Admin Role : Role that will have administrator permission level. Need to be inside Thread Server.
    • Moderator Role : Role that will have moderator permission level. Need to be inside Thread Server.
    • Mentioned Role : The role that will be mentioned on new thread. Need to be inside Thread Server. *Optional
  2. Mention the bot followed by setup message to start bot setup and reply to the bot message to proceed. e.g. @ModMail setup

V. Setting up UptimeRobot

If you have Replit Hacker Plan, turn your Replit project to always on and ignore this part of instruction.

You can also skip this part if you aren't hosting it on Replit.

  1. Create UptimeRobot account and login.
  2. Go to Dashboard and click + Add New Monitor button.
  3. Select HTTP(s) for Monitor Type and fill the name section.
  4. Copy your Replit project webserver link and paste it to URL section. e.g. https://projectName.replUsername.repl.co
  5. Set the Monitoring Interval to 30 minutes and then click Create Monitor button at the bottom.

Adding another Language

  1. Go to locale folder.
  2. Copy template.txt and rename it to designated language name and change the file type to javascript .js.
  3. Fill the empty quotes "" with the translation while using en.js as reference.
  • Notes :
    • I recommend to only have up to two language per bot to make cleaner user experience.
    • User experience would be better if you have different bot for different language.
    • Most of message command response are hard coded so it won't be affected.
    • Make sure the name property is same as the filename. e.g. en.js name: "en"
    • Make sure there's no same command name within and between language as it will throw an error when deploying the command.
    • Make sure to not leave any property value empty since it might trigger an error.

Command List

Slash Commands

*Global Command **Optional

Name Operation Description Usage
/block info Show specified user information /block operation:info target:userID
list Show blocked users list /block operation:list page:number**
add Block specified user /block operation:add target:userID reason:blockReason
set Edit specified user blocking reason /block operation:set target:userID reason:newReason
remove Remove specified user from blocked list /block operation:remove target:userID
/close - Close an active thread /close reason:closeReason note:threadNote** anon:true**
/config view Show current bot configuration /config operation:view
info Show specified config information /config operation:info target:configName
set Edit specified config value /config operation:set target:configName value:newValue
reset Reset specified or all config value /config operation:reset target:configName
/create* - Create new thread /create title:threadTitle
/help* - Show specified command information /help target:commandName
/ping - Calculate bot latency /ping
/reply* - Reply an active thread /reply content:message anon:true
/tag view Show a saved response /tag operation:view target:tagName show:true**
sent Sent a saved response to an active thread /tag operation:sent target:tagName
info Show tag information /tag operation:info target:tagName
list Show tag list /tag operation:list page:number
add Create new saved response /tag operation:add target:tagName content:tagContent
set Edit a saved response content /tag operation:set target:tagName content:newContent
remove Remove specified tag /tag operation:remove target:tagName
/thread info Show specified thread information /thread operation:info user:targetUser
/thread operation:info channel:targetChannel
list Show thread list /thread operation:list page:number**
bind Bind a user thread to a channel /thread operation:bind user:targetUser channel:targetChannel title:threadTitle**

Message Commands

If ownerID are set, only owner can use these commands.

⚠️ If ownerID are empty but mainServerID or threadServerID are set, only admin from those servers can use these commands.

⚠️ If ownerID, mainServerID, and threadServerID are empty, any admin from any server can use these commands.

Name Description Usage
config Show current bot config @ModMail config
deploy Deploy slash commands @ModMail deploy
guilds Show list of guilds(servers) the bot in @ModMail guilds
leave Leave specified guild(server) @ModMail leave guildID
reload Reload specified command, function, or locale file @ModMail reload targetName
reset Reset all or specified config value @ModMail reset all
@ModMail reset configName
set Edit specified config value @ModMail set configName configValue
setup Set required bot config and deploy slash command @ModMail setup

Testing

I made Discord server to test the bot, feel free to join at https://discord.gg/bzG7AqcRyC.