Skip to main content
Please Note
Welcome to the new documentation! Please bear with us as we complete migrations to this platform!

Configuring Your ModMail Instance

Configuration Guide

ModMail features a variety of variables that you can configure to personalise it to your server, this guide will explain which each variable does and how to set them! We will be using Hydra's default prefix throughout this guide which is m/, make sure to replace this with your configured prefix when following the commands.


As there is a large number of configuration options, we recommend using the quick selection on the right side of this page to quickly navigate around!

Changing Prefixes

ModMail Prefix

Want to change your bots' default prefix? You can use m/set prefix <New Prefix> as seen below. Your new prefix must be less than 45 characters.

Changing Prefix

Canned Prefix

When using canned responses, you can customise the prefix that you need to use in threads to activate them by using the following command m/set cannedPrefix <New Prefix>. By default, the canned prefix is !!<CannedName>.

Changing Canned Prefix

Anonymous Canned Prefix

Similarily to changing the canned response prefix, you can also customise the anonymous canned respond prefix using m/set anonCannedPrefix <New Prefix>. By default, the anonymous canned prefix is !!!<CannedName>.

Changing Anonymous Prefix

Customising Your Instance's Appearance

The Avatar

You can customise your instance's avatar at any time by using m/set avatar <File Upload / Image URL>, an example of using this command is below. Please note, you may need to refresh your client to see the avatar change take place.

Changing Avatar

The Username

You can change the username of your modmail instance using m/set username <New Username>. If you are encountering an error when changing your username, it is likely that there is already too many users with that name as Discord has limited discriminators.

Changing Username

The Status

Customising the status of your instance is easy! You can use the m/set status <Status ID> <New Status> command and it will instantly update to "Status Type[Your Message Here]". You can find a breakdown of each status ID below.

Status IDStatus Type
0 Playing Your Message Here
2 Listening to Your Message Here
3 Watching Your Message Here
5 Competing in Your Message Here

Your Hydra instance will only edit the part of the status that you specify, for example. If you used m/set status DM to Contact Staff!, it will remain on status ID will and keep the status as Playing.

Changing Status

Status Example

Alternatively, if you just want to change the status type, keeping the message the same, you can use m/set status <Status ID>.

Public Reply Message (Optional)

A public reply message allows you to set a customisable message which ModMail will reply with, when it is pinged / mentioned within your server. You can set a reply message using m/set publicReply <Message>.

Setting Public Reply

Once your public reply message is set, everytime your ModMail instance is mentioned, you will see a response like the example below!

Public Reply Example

Thread Messages

Thread Warning Message

A thread warning message is the first message that is sent to the user after they have DMed your ModMail instance, it acts as a confirmation for whether the user wants to open a ModMail ticket or not. You can set the warning message with m/set warn <Warning Message>.

Setting Warning Message

You can see an example of how a warning message looks below, with a submit and cancel button depending on whether the user wishes to proceed on creating the thread.

Warn Message Example

Thread Opening Message

The thread opening messages comes after the warning message, if the user decides to confirm. This can be used to give your users rough estimates on how long to wait for a response, and more. You can set this using m/set create <Thread Opening Message>.

Setting Opening Message

Once configured, your opening message will be sent to users who open new ModMail tickets as seen in the example below.

Opening Message Example

Thread Closing Message

Similarily to the opening message, the closing message is given to the user after a ModMail thread is closed. You can set your own customised close message using this using m/set close <Thread Closing Message>.

Setting Closing Message

Once a ticket is closed, your closing message will be sent to the user, with an example attached below.

Closing Message Example

Thread Options

Setting Main Guild

The instance main guild is the server where users will DM the bot from, to create their ModMail threads. This can be changed using m/set guild <Guild ID>, you will need to ensure that the bot is already within the new main guild before using this command otherwise an error will occur. Below is an example of setting the main guild via ModMail.

Setting Main Guild

Mail Guild (Optional)

Optionally, you may also use a mail guild, this is a separate guild from your main guild where tickets will be sent to instead. Before setting a mail guild, please ensure that your instance is already within the server that you are planning to use. You can set a mail guild using m/set mail <Guild ID>, after which all new tickets will be forwarded to that guild instead of your main.

Setting Mail Guild

Please note

If you decide to utilise a mail guild, you will need to re-configure both your category and permissions as these will customised with the new variables from your mail guild. If you do not configure these variables, ModMail may not behave correctly and tickets may be undelivered.

Setting Categories

Want to change the category that new ModMail threads are sent to? You can use m/set category <Category ID> and all new tickets will be forwarded there!

Setting Category

Log Channel

A log channel is where log links will be sent once open threads are closed, you can change your log channel at any time using m/set log <Channel ID>.

Setting Log Channel

Once set, log channels will send log links like the example below. Please note that the URLs are OAuth protected, users require permission level 2 or above to be able to read URL logs.

Log Example

Working Category (Optional)

Optionally, you can use a working category. This is a separate category that tickets will be sent to after a staff member has replied within a thread that is within the main category. You can set this up using m/set workingCategory <Category ID> as seen below.

Setting Working Category

Want to stop using a working category? Simply re-run m/set workingCategory without providing any category ID as seen below and it will be reset.

Resetting Working Category

Channel "Prefix" (Optional)

A channel prefix alters the format of channel names. For example, a channel prefix of support will make all new threads following the format of #support-[USERNAME]-[0000]. This is useful if you have multiple Hydra instances and need to diffentiate between tickets from each bot. Channel prefixes can be set using m/set channelPrefix <Channel Prefix>, please note there is a 8 character limit on channel prefixes.

Setting Channel Prefix

Example Channel

Similarily to working categories, if you want to clear your channel prefix, you can run m/set channelPrefix without providing a prefix as seen below.

Resetting Channel Prefix

Minimum Account Age (Optional)

You can set a minimum age for creating threads, this is useful for spam prevention. To enable a minimum account age, you can use m/set age <Age (In Days)> as seen below.

Setting Age

If a user tries to open a thread and they do not meet the minimum account age, they will receive the error below.

Age Error

User Closing Notification (Optional)

Optionally, you can configure Hydra so users will see a notification (such as the example below) 10 minutes before their thread is automatically closed when using a closing timer. You can enable/disable this feature using m/set timedUserNotify <true/false> as seen in the commands usage below.

User Close Notif Example

User Close Notif

Staff Typing Indicator (Optional)

By default, when typing within a thread channel, Hydra will display in the users DMs that it is typing.... You can disable or enable this function using m/set indicateTyping <true/false>.

Typing Indicator Example

Typing Indicator Enable

Notify Message (Optional)

You can create a custom notify message to be included on new threads by using m/set notify <Notify Message>, this is useful for pinging available staff members or reminding them of policies.

Creating Notify Message

An example of how a notify message looks within a ModMail thread can be seen below.

Notify Example

Notify On Staff Created Tickets

You can disable whether the notify message is displayed on tickets that are opened via the m/new command using m/set notifyOnStaffCreate <true/false> as seen below.

Staff Notify Example