On this page
Before you start
Three words you will see
- Panel
- The message with the buttons on it. Members press a button to open a ticket.
- Ticket type
- One button. Each type has its own staff role, intake questions and archive channel.
- Rank
- A number from 1 to 10 you give a staff role. Higher ranks can do everything lower ranks can.
Step 1
Add the bot
- Add ModMailBot to your server, picking the server from the dropdown on Discord’s screen. Adding a bot needs the Manage Server permission. Running
/setupafterwards needs Administrator, or a rank 5 role that an Administrator has also allowed (step 2). If you own the server, you have both. - Approve the permissions. The screen lists only what the bot uses (the full list shows what each one is for), and Administrator is not on it. Picked the wrong server? Remove the bot there under Server Settings → Integrations and open the link again.
- The bot DMs you instructions. If you miss it, just run
/setupanywhere in the server.
Step 2
Run /setup
Discord shows /setup only to Administrators; an Administrator can allow it for other roles under Server Settings → Integrations → ModMailBot → Commands. The bot also wants such a role mapped to rank 5 with /config staff set. Its replies are private to you. Every choice saves as you make it, you can step back with ◀ Back, and re-running resumes where you left off.
Pick Quick setup. Custom setup is for servers that want several staff ranks or more than one ticket type, and you can switch later by re-running /setup.
Quick setup ~5 min
Choose your staff role. It becomes rank 2: it can take, close and archive tickets and block members, while changing settings stays with Administrators until you map a rank 5 role and allow /config and /panel for it under Server Settings → Integrations → ModMailBot → Commands. Let the bot create your channels (a Support category with a read-only panel channel, a private archive, and a private log) or pick your own, publish the panel, then post an announcement if you like. Ends with a permissions check.
Custom setup
Set up several staff ranks (for example Staff → rank 2, Managers → rank 4, Bot admins → rank 5), several ticket types with their own ping roles, and your own panel text.
If you let it, the wizard creates three channels in one category (contact-us, ticket-archive and ticket-log); otherwise it uses the ones you pick. Either way it finishes with a permissions check. Each ticket gets its own temporary channel in the ticket category. If the check names a problem, fix it in Discord and run /diagnose. See exactly what it adds to your server →
Come back to /setup whenever you like. Once you are configured it opens with an Adjust a section… menu (Staff ranks, Channels, Ticket types, Panel) that jumps straight to the part you want.
Step 3
Check your panel
The wizard publishes a panel with one ticket type on it, named Contact Us. Press the button yourself. You should land in a private channel named after you and the ticket type, like #yourname-contact-us.
Members can only press what they can see. If you pointed setup at a channel you already had, @everyone needs View Channel and Read Message History there, and the bot needs Send Messages and Embed Links. An archive or log channel has to be staff-only: the bot refuses a public one.
You can rename that type, add more departments and add intake questions later; all of it is in the reference. You do not need any of it today.
Warning: Button did nothing? Run /diagnose. It names the exact permission or setting that is missing.
Step 4
Close your test ticket
When a member opens a ticket, your staff role is pinged in a channel only your staff and that member can see, with the intake answers already posted. Staff answer there, under their own names.
You opened a ticket in step 3. Close it the way your staff will: run /close in that channel and press Confirm closure, then run /archive. Within a few minutes, the transcript lands in #ticket-archive and the channel disappears. Pressing the panel button again while your test ticket is open, or within 60 seconds of it, is refused on purpose.
A ticket has three states. Open: the member and staff can talk. Closed: the member is locked out, the channel stays for staff, and /reopen lets them back in. Archived: the transcript is saved and the channel is deleted, which cannot be undone. Turn on auto-archive for a type if you want closing to archive in one step.
Two commands cover the life of a ticket, and a third opens one from the staff side:
| Command | What it does |
|---|---|
/close | Proposes closing. The member sees a countdown plus Confirm closure and I need more assistance. |
/archive | Saves the transcript to your archive channel, then deletes the ticket channel. |
/create user:@member | Opens a ticket with a member. Also on right-click → Apps → Open Modmail (long-press on mobile). |
Everything else (blocking, reopening, forcing a close) is in the full command list.
Optional
Restrict who can run commands
Skip this if you are happy with the defaults. ModMailBot already checks staff ranks itself before every staff and admin command runs, so what follows adds Discord’s own check on top of it.
Open Server Settings → Integrations → ModMailBot. You land on the Command Permissions screen. It has three layers, in this order: Roles & Members, Channels, then a Commands list. The first two set the app-wide default; the Commands list overrides that default one command at a time. A command runs when its role gate and its channel gate both allow it.
Recommended settings
| Layer | Set it to | Why |
|---|---|---|
| 1. Roles & Members | Deny @everyone, and leave it as the only entry | This is the app-wide default for every command. Denying @everyone here hides the whole bot from ordinary members in one place, rather than switching off nineteen commands one at a time. Any role you add to a command in row 3 overrides it for that command. |
| 2. Channels | All Channels, allowed. Never deny this | The channel gate is checked separately from the role gate. Ticket channels are created one per ticket, after you set this, so no list chosen in advance can include them. Deny it and /close, /forceclose and /archive stop working inside the ticket, which is the one place staff need them. |
| 3. Commands | Open each command your staff need and add the roles that should run it | A role you add here replaces the app-wide default for that one command, which is how the bot comes back to life for staff after row 1. Add your handler roles to /close, /archive, /create, Open Modmail, /block and /unblock; add whoever administers the bot to /setup, /diagnose, /config and /panel, and give that role rank 5 with /config staff set as well, or the bot will still refuse. Leave each command’s own Channel Overrides empty. |
Warning: The Channels row is the trap. Restrict by role, never by channel.
Denying @everyone in row 1 hides every command from members, /help included. /help tells members how to open a ticket, so to keep it, open it in row 3 and allow @everyone. /support, /feedback, /bugreport, /version and /ping exist for your staff to reach this bot’s developer, so members not seeing them is usually what you want; add a role to any you would rather keep visible.
Changed something here? Run /diagnose. It spots a denied All Channels row and warns you before your staff run into it.
You’re live
Nothing below is required. Come back when you want it.
Reference
Every command, ticket types and intake forms, staff ranks and who can see what, archiving, and the permissions the bot needs.
Help
Buttons not responding, nobody getting pinged, the bot showing Administrator, or an Integrations setting breaking staff commands inside tickets.