On this page
Commands
Members never need a command; they press a panel button. The commands below are for staff, except the last three rows, which the bot lets anyone run.
| Command | Who the bot allows | What it does |
|---|---|---|
/create user:@member (type optional) | rank 2 and up | Open a ticket with a member (also via right-click → Apps → Open Modmail, long-press on mobile). A type you can’t see yourself is refused; the form and the cooldown are skipped |
/close | type's close rank (default 1) | Propose closure; the member sees a countdown plus Confirm closure / I need more assistance |
/forceclose | rank 4 and up, or the type's close rank if that is higher | Close immediately, no member confirmation |
/reopen | type's close rank (default 1), so whoever can close a ticket can reopen it; you can require a higher rank with /config staff gate. A server that used the bot before this default kept rank 4 (/config view lists it), and a type’s higher close rank still applies | Reopen a closed ticket; the member regains access |
/archive | type's archive rank, or its close rank if none is set (default 1) | Save the transcript of a closed ticket to the archive channel, then delete the ticket channel, within a few minutes |
/block · /unblock | rank 2 and up | Stop / re-allow a member opening tickets |
/setup · /diagnose | rank 5 and up; Discord hides them unless you have Administrator or an Administrator allowed them under Server Settings → Integrations → ModMailBot → Commands | Guided setup; check every permission the bot needs |
/config … · /panel … | rank 5 and up; Discord hides them the same way | Ticket types, staff ranks, timing and log channel (below); add panels, choose their buttons, and rebuild, retext or delete them |
/data delete | Manage Server | Erase all of this server's bot data from our database now and delete the bot's panel messages (confirmation required); backup copies are gone within 90 days. A panel it can't reach is named for you to delete. Your channels and transcripts stay |
/help | anyone | Show how the bot works for members, staff and admins, with links to the setup guide, this page and the support server. Only the person who runs it sees the reply |
/support · /feedback · /bugreport | anyone | Get the support server invite, or send feedback or a bug report about ModMailBot itself to its developer. What you type is sent with your username, user ID, server ID and the bot version, never ticket content. It’s one way: for a reply, ask in the support server |
/version · /ping | anyone | Show the running bot version; confirm the bot is answering |
The middle column is the bot’s own rank check. Whether someone sees a command at all is Discord’s decision, made under Server Settings → Integrations → ModMailBot. So anyone here means the bot will not refuse them, not that everyone can see it: if you denied @everyone on that screen, even those rows stay hidden from members until you add a role back for that command.
/create without a type, and right-click → Apps → Open Modmail, both open your first ticket type. /config view tags which type that is, and you can change it by reordering.
/bugreport is for bugs in ModMailBot, not in your own server; members use the panel for those. If members might confuse it with a Bug button on your panel, keep it off their list: denying @everyone under Server Settings → Integrations → ModMailBot → Roles & Members already covers it, and so does a deny on that one command.
A member can have one open ticket per type at a time. Ticket channels are named after the member and the type, like sam-report-a-member, and open with the welcome message and the intake answers already posted.
Ticket types
Every button on your panel is a ticket type, and a type’s name is its button label: rename one and the button, pickers, archive summaries, and future transcript filenames all follow. The wizard seeds one type named “Contact Us”. A panel holds up to 25 buttons, and each panel shows the types you choose for it.
“Contact Us” appears twice above and is set by two different commands.
What a member fills in before the channel opens. The numbering carries on from the panel above: box 2 is that same ticket type, now seen from the member’s side. Turn the whole form off for a type with /config ticket form.
Ticket type commands, by what they change
| Command | What it does |
|---|---|
| On the panel | |
/config ticket edit (name:, sort:, style:) | Rename it, reposition it (sort: 1 = first = the /create and Open Modmail default), or change the button color (style: 1 blurple, 2 grey, 3 green, 4 red) |
/config ticket emoji | The button’s emoji |
| In the ticket channel | |
/config ticket intake | Up to five questions members answer before the channel opens (labels up to 45 characters) |
/config ticket form | Turn the form on or off for this type; off means the ticket opens on the first press |
/config ticket placeholder | The grey hint inside an answer box (up to 100 characters), e.g. format examples or “say none” |
/config ticket welcome | The message posted when a ticket opens; supports {user_mention} and {role_mentions} |
/config ticket edit (category:, ping_role:, view_role:, clear:) | Where the channel is created; the role that is pinged (it also gains access, and setting it without view_role: replaces the view role); a role that can see and reply without being pinged; or clear any of them |
/config ticket escalation-role | A role pinged when a member presses I need more assistance on a close proposal, instead of the ping role; clear it to fall back |
| In the archive | |
/config ticket edit (archive_channel:) | Which channel receives this type’s transcripts. It must be staff-only, and the bot must be able to post files there: a public channel is refused, and so is one the bot can’t use, with what it lacks named |
/config ticket auto-archive | Archive automatically when a ticket of this type closes. It switches itself off, with a notice, if the bot can’t use the archive channel; a ticket that fails 3 times is left for you to archive by hand |
/config ticket archive-rank | Minimum staff rank to archive this type. Ranks at or above it are also given read access to its archive channel; roles that could already read it keep that |
| The type itself | |
/config ticket add | New type; inherits channels and staff role from your first |
/config ticket remove | Take a type off your panels. If it was never used for a ticket, it’s deleted. If it was, it’s kept for those tickets, and /config view lists it under Removed ticket types. Your last type stays: add its replacement first |
/config ticket restore | Bring back a removed type, with its settings, in the place it had |
/config ticket close-rank | Minimum staff rank to close this type |
Your panels update themselves when you add, remove, rename, reorder or recolor a type. With one panel, a new type goes on it; with panels in two or more channels, /config ticket add asks which ones show it. A daily check also compares every panel with your settings: it fixes one that doesn’t match and re-posts one whose message was deleted. /panel repair does the same for all your panels right away.
Server settings and panels
Everything here needs rank 5 or higher, and Discord shows /config and /panel only to Administrators unless you allow them under Server Settings → Integrations → ModMailBot → Commands. Defaults are what a fresh server gets; change them any time. The commands that map roles to ranks are in the next section, with the ladder they feed.
| Command | What it does |
|---|---|
| Timing and limits | |
/config settings close_timeout: | Seconds before an unanswered close proposal closes the ticket. Default 300 (five minutes); 30 to 86,400. A change applies to closes proposed after it; a countdown already running keeps the time the member was shown |
/config settings cooldown: | Seconds a member waits between opening tickets. Default 60; 0 to 3,600. Staff using /create skip it |
/config settings throttle: | Maximum new tickets per minute for the whole server. Default 10; 1 to 50 |
| Channels and records | |
/config log-channel | Where the bot posts its notices: archives run with /archive, archive and ticket-creation failures, data deletions, and the occasional announcement about the bot itself. Never message content. It must be staff-only: a public channel is refused. The bot gives itself access to the channel before it saves it; a channel it still can’t post in is refused, with what it lacks named. If the bot can’t see the channel at all, add its role to the channel first |
/config cleartickets user: | Close a member’s stuck ticket records: open in the bot, but their channel is gone. Live tickets are left alone and named in the reply; close one with /forceclose in it |
/config view | Show staff ranks, ticket types (including which is first), your panels and their buttons, command gates, the log channel and any removed ticket types. Types that no panel shows get a section of their own |
| Panels | |
/setup (panel step) | Publish your panel in the channel you pick, with the ticket types your panels offer (every type, for your first). Publishing again in its channel updates it in place. /panel repair re-posts a missing one |
/panel add channel: | Put a panel in another channel: pick the ticket types it shows and its text, then publish. A channel that already has a panel is refused |
/panel buttons (channel:) | Choose which ticket types a panel shows. Leave out channel: and it opens your only panel, or lists your panels to pick from when you have more than one. A panel keeps at least one button |
/panel settext (channel:) | Change the heading and body text of your panels, or of the panel in one channel |
/panel repair | Rebuild every panel now from your settings, text and buttons; re-posts one whose message was deleted |
/panel delete | Remove a panel for good. A panel deleted by hand is posted again by the daily check |
Staff ranks and who sees what
Two different things are decided here. A rank decides which commands someone can run. A ticket type decides which tickets they can see. They are set separately, so read both halves before planning your roles.
Mapping roles to ranks
| Command | What it does |
|---|---|
/config staff set rank: role: (name:) | Map a role to a rank from 1 to 10, optionally naming it |
/config staff remove | Remove a rank mapping |
/config staff gate command: rank: | Raise or lower the minimum rank for a command (the defaults are in the ladder below; a role must be mapped at that rank). Not /close or /archive: those follow the type’s close rank and archive rank |
What each rank unlocks
Staff access is organized into ranks 1–10 that you map to your roles. Higher ranks inherit lower ones. These are the built-in minimums; /config staff gate overrides any of them: pass a command: and a rank: from 1 to 10.
Discord Administrators pass every rank check. /data delete sits outside the ladder too: it needs Manage Server, so it can’t be delegated to a rank.
| Rank | Example role | Unlocks at this rank |
|---|---|---|
| 6–10 | yours to define | Nothing new by default |
| 5 | Bot admins | /setup/config/panel/diagnose |
| 4 | Managers | /forceclose |
| 3 | unused by default | Nothing new by default |
| 2 | Moderators | /create/block/unblock |
| 1 | Helpers | /close/reopen/archive |
Role names are examples; you map your own. /close, /reopen and /archive sit at rank 1 because that is the default close rank, which is per type and can be raised. Discord itself hides /setup, /diagnose, /config and /panel from anyone without Administrator unless you allow them under Server Settings → Integrations → ModMailBot → Commands, so on a fresh server the person running setup needs Administrator. A rank only unlocks commands. Seeing a ticket is decided per type (below): with the wizard’s defaults the floor is rank 2, so a rank 1 role sees no tickets unless you attach it to a type as a view role.
Who can see which tickets
Seeing a ticket is decided per ticket type, by two rules that work together.
- The roles attached to a type always see it. That means the type’s ping role, view role and escalation role, whatever rank they hold. Attaching a role is the direct way to give someone access.
- Every other staff member sees it from one rank upward. That cut-off is whichever is higher: the lowest rank among the roles attached to the type, or the type’s close rank.
Archiving has its own rank. /config ticket archive-rank sets the minimum rank to run /archive on this type, so handlers can close a ticket while a senior rank does the archiving. From then on, read access to the archive channel is granted to the ranks at or above it. Access that was already granted, for example to the staff role the wizard set up, stays until you remove it in the channel’s permissions, and one archive channel shared by several types is readable by every one of those types’ roles.
Three types, three floors
Ask a mod
- Roles on the type@Mods · rank 2
- Close rank1 (default)
Rank 2 and up.The ordinary case: the role you attach decides who else inherits it.
Ban appeal
- Roles on the type@Admins · rank 5
- Close rank1 (default)
Rank 5 and up.Handing a type to a senior role is all it takes to keep it senior-only.
Report a member
- Roles on the type@Mods · rank 2
- Close rank4 (raised)
Rank 4 and up.Raising the close rank lifts the floor for everyone else, but @Mods still sees it.
The roles you attach always keep access. The cut-off only decides which other staff ranks inherit it, and it is whichever is higher: the lowest-ranked role on the type, or its close rank.
Archiving
When you archive a ticket, the bot builds a self-contained HTML transcript (plus a plain-text copy) named after the member and the type, like sam-report-a-member-transcript.html, re-uploads the attachments so they survive the channel being deleted, posts everything to your archive channel, and only then deletes the ticket channel. If any step fails, the channel is kept so you can retry, and long tickets are split into numbered parts rather than truncated (up to the newest 10,000 messages).
- Attachments are re-uploaded up to your server's own upload limit, less a small margin: about 9 MB per file at Boost levels 0 and 1, 49 MB at level 2 and 50 MB at level 3. Each archive holds up to 40 attachments or 100 MB in total. Anything over a limit is listed by name in the transcript, never silently dropped.
/reopenworks on closed tickets. Archiving is final: the channel is deleted once the transcript is posted.- Discord allows 50 channels per category. Archive closed tickets (or turn on auto-archive), and give busy types their own category with
/config ticket edit category:. - A member’s attachment that can run code (
.html,.svg) is re-uploaded with a.txtsuffix and flagged ⚠️. This applies to attachments only: the transcript the bot writes keeps its own.htmlname.
Warning: Keep the archive channel staff-only, since transcripts can contain everything a member shared. The bot refuses an archive or log channel that is public: one @everyone can see, or, on a server that gives members View Channel through a role (a verified role, say), one that role can see.
Warning: Archiving copies everything left in a ticket, files included, into your archive channel. If a ticket contains illegal content, report it to Discord with Report Message and delete it before archiving. If it’s already archived, do the same with the transcript.
Bot permissions
ModMailBot follows least-privilege and never needs Administrator. Run /diagnose to check everything below; it also warns if an archive or log channel is public, if a role attached to the bot grants it Administrator (it names the role), and if a channel restriction in Server Settings → Integrations would break staff commands inside tickets.
Permissions the bot needs
| Permission | Where it has to hold | Symptom if missing |
|---|---|---|
| View Channels | panel channel, ticket category, archive and log channels; server-wide if your server turns it off for @everyone. Not in the install link | The bot can’t work in that channel |
| Manage Channels | server-wide, as the install link grants it | "Ticket creation failed" after the form |
| Manage Roles (shown as Manage Permissions in a channel’s or category’s settings) | every category you use for tickets | Closed tickets don't lock out the member |
| Send Messages Embed Links | panel, ticket, archive, log | Silent or broken-looking messages |
| Attach Files | archive channel | Archive fails |
| Read Message History | ticket channels | Empty transcripts |
| Mention @everyone, @here, and All Roles (or make the ping role mentionable) | ticket channels; not in the install link | Staff never pinged on new tickets |
Adding the bot grants every row above except two: View Channels and Mention @everyone, @here, and All Roles. The bot does not ask to see your whole server. It sees what your server shows everyone, the channels the setup wizard creates, and, where it can, the panel, archive and log channels you pick. If a channel or category you pick is hidden from @everyone, add the bot to it. If your server turns off View Channels for @everyone (behind a verification step, for example), give the bot’s role View Channels instead: Discord only lets a bot grant permissions it has server-wide, so without it the bot can’t create ticket channels. For the same reason, keep Send Messages, Embed Links, Attach Files, Read Message History and Manage Channels server-wide, as the install link grants them: every ticket channel gives them, so moving one to a category breaks ticket creation. For mentions, either grant that permission to the bot in the ticket category or make the ping role mentionable. /diagnose checks each channel the bot uses for what that channel needs, and warns when a ping role can’t be mentioned. It also warns first when the bot is missing, server-wide, a permission every ticket channel needs. Leave Manage Roles as it is: the bot updates who can read the archive and log channels when you change staff ranks.
Something not working?
Buttons not responding, nobody getting pinged, the bot showing Administrator, or an Integrations setting breaking staff commands inside tickets: those all have answers on the help page.