Before you proceed
-
Modmail is a self-hosted private bot intended for a single server use case.
As Modmail is written with single-server use case in mind, it is not advised nor recommended to have your bot in servers other than the one specified inGUILD_ID
orMODMAIL_GUILD_ID
due to the way it handles the threads and channels internally. -
This Modmail is different from the original Modmail bot by kyb3r and has incompatible changes.
As such, plugins made for the original bot may not work properly on this instance. Consult the plugin author to determine the compatibility. -
Using this code revokes your official support eligibity from the official Modmail staff.
Using a modified codebase automatically disqualifies you from getting official support. Issues, questions and concerns can be raised in the support server made for this instance at https://dsc.gg/transience (opens in a new tab).
Basic requirements
There are three components for Modmail:
- The bot program
This is your main bot process which does all the heavy lifting. - The database
Modmail uses MongoDB as the database program. All operational data is stored here. - Logviewer webserver
A web app used to view the thread transcripts via your browser. Optional but recommended.
Create a Discord bot
The first step in setting up Modmail is to create a Discord bot. Head over to the Discord Developer Portal and create a new application.
Once you've created a new application, head over to the Bot tab and create a new bot.
![Hello](/_next/image?url=%2Fcreate-bot.png&w=1920&q=75)
Click Add bot to create the bot. After adding a bot, reset the token and copy and store the newly generated token in your Text editor for later use.
![Hello](/_next/image?url=%2Freset-token.png&w=1920&q=75)
Make sure to keep this token private! Anyone who has this token can control your bot and potentially cause malicious damage.
Next, we need to change some bot settings. Toggle off public bot, then toggle on both server members intent and message content intent. Remember to click on Save Changes.
Why do I need to do this?
Disabling public bot prevents other users from inviting your bot. Your bot may not behave appropriately if it's present in other servers.
Enabling server members intent allows Modmail to view your server's members list and efficiently populate the bot's internal cache.
Enabling message content intent allows bot commands to function since Modmail doesn't use slash commands.
What about presence intent? It is not needed for Modmail, but it may be required for specialized plugins. We recommend keeping this toggled off to save computational resources.
Invite the bot
Navigate back to the General Information tab and copy the application ID. Click Copy to copy the application ID. This is also known as your "Bot ID".
![Hello](/_next/image?url=%2Fbot-id.png&w=1920&q=75)
Using the following URL as template, replace YOUR-ID-HERE
with the ID you just copied. Do not change anything else! Open a new browser tab and go to that URL.
https://discord.com/oauth2/authorize?scope=bot&permissions=416075476184&client_id=YOUR-ID-HERE
Discord should prompt you to choose a server to invite your bot, followed by a list of permissions. Scroll to the bottom and click Authorize. Choose your server to invite, then click Continue.
![Hello](/_next/image?url=%2Finvite-bot.png&w=1920&q=75)
Scroll to the bottom and click Authorize. Don't un-check any permissions. Only Administrator is optional.
You must leave on all permissions excepted for Administrator (optional). However, we recommend allowing Administrator for ease of setup and to avoid complications with Discord permissions.
Do you have a separate staff server?
If you manage a large server where you have a separate server for communication among your moderation team, Modmail supports directing threads into the staff server instead of your main (public) server.
You will need to invite your Modmail bot to both your main (public) server and your staff server using the same invite link above.
Your bot should now be offline in your server. Congratulations, that's as expected! You have successfully created a Discord bot. The next step is to create a MongoDB database.
Create a MongoDB database
Modmail uses MongoDB to store its internal configurations and log histories. You must create a MongoDB database in order to use Modmail.
You can use MongoDB Atlas (opens in a new tab) as they allow a free 512MB storage instance which is more than enough for Modmail, though it is also possible to self-host the database on your own machine, you may skip this step if you intend to self-host the database.
Head over to MongoDB Atlas (opens in a new tab) and register for a free account:
Once you've registered and confirmed your email, you will be greeted by the MongoDB welcome introduction, asking you to "tell us a few things about yourself and your project". You can answer these questions honestly or however you like.
In the next step for "deploy a cloud database", choose the Shared option. Choose the region that's closest to where you're hosting your bot. Make sure the Cluster Tier is set to M0 Sandbox and the price shows as FREE.
![Hello](/_next/image?url=%2Fmongo-shared.png&w=1920&q=75)
On the following Security Quickstart page, do the following:
- Authentication method: Username and Password
Username: `modmail` Password: Click **Autogenerate Secure Password** - don't type your own password!
- Copy and save the password into your text editor, you will need this for later. From now on, we will be referring to these credentials as the database username and database password.
- Click Create User.
- Scroll down, we will be connecting from: My Local Environment
- Set IP address as
0.0.0.0/0
and anything for the description.You must set the IP address exactly to this, unless you know what you're doing. Do not set it to anything else or click add my current IP address. This allows Modmail to connect to your database.
- Click Add Entry.
Next, we will need to generate a MongoDB connection string. Simply click Connect
on the main dashboard,
choose Connect your application
, then copy the connection string (the default driver is fine) and paste it into your Notepad.
![Hello](/_next/image?url=%2Fmongo-connect.png&w=1920&q=75)
If you followed all the steps so far, your Notepad should contain three lines: the bot token, the database password, and the MongoDB connection string. For example:
My bot token: MTA3Djv3IAxNjk1NDgdKD231.G1AoUjD.5z629aKP34JKHn4v1EsdNUwdDO3MvBR9ifVES4
My database password: elAO7wF1r07pNG6u
My MongoDB connection string: mongodb+srv://modmail:<password>@cluster0.example.mongodb.net/
Finally, you will need to combine the database password with the MongoDB connection string by replacing
the <password>
(including the <>
) with the database password.
You also need to remove everything after .mongodb.net
at the end of the MongoDB connection string.
This is what your Notepad should look like at the end of this step:
My bot token: MTA3Djv3IAxNjk1NDgdKD231.G1AoUjD.5z629aKP34JKHn4v1EsdNUwdDO3MvBR9ifVES4
My MongoDB connection string: mongodb+srv://modmail:[email protected]
Preparing your Environmental Variables
Once you have finished the previous steps, gather and save the variables listed below as they will be needed to run your bot in later steps:
TOKEN
- The token to run your Modmail application under your Discord bot accountLOG_URL
- [Optional] Logviewer URL that will be used to view threads in your web browserGUILD_ID
- The ID of the main Discord server that your bot will operate in.MODMAIL_GUILD_ID
- [Optional] The ID of the Discord server that your bot will create ticket channels in. This is only needed if you want your ticket channels to be created in a separate server, for an example, Staff Server.OWNERS
- The user ID of the Discord accounts you want to set as owner for the bot. Can consist of multiple users, separated by comma.CONNECTION_URI
- The URI the bot will use to connect to your MongoDB instance.
Your finished variables should look something like this:
TOKEN=OTY3Nzy5MzU5NjAzMzU2NzE4.GtKp_5.JOTYRwGW-LB1He5widCu73vXtmi90KxsqkmoOg
LOG_URL=https://logs.mymodmailbot.com/
GUILD_ID=1079074933008781362
OWNERS=188363246695219201,231595246213922828
MONGO_URI=mongodb+srv://username:[email protected]/
Hosting Modmail
Your next step is to choose one the hosting method that's preferable to you. Each method has their pros and cons, be sure to take them into consideration when choosing your hosting platform to run Modmail.
For hosting on a personal device or VPS, refer to the "Installing Modmail" section as we cover some widely used OS on our guide.
For hosting on a Cloud platform (PaaS) like Railway, Northflank or Koyeb, refer to the "Community Guides" section as these platforms are often proprietary and closed source and may affect which may affect the viability of the guides.
Community Guides