What it does
ModMailBot turns a button into a private support conversation between a member and your staff. Every ticket follows the same path:
- You post a panel (a message with one or more buttons) in a public channel.
- A member presses a button and fills out a short form.
- The bot opens a private channel that only that member and your staff can see.
- When it's resolved, staff propose closing. The member confirms, or it auto-closes after a countdown.
- You archive it: a readable transcript (images included) is saved to a private channel you choose, and the ticket channel is deleted.
What you can configure
- Custom ticket types: as many buttons as you need, each with its own name, color, emoji, ping role, archive channel, welcome message, and intake form.
- Intake forms: ask up to five questions before the channel opens (optional per type).
- Tiered staff access: ranks 1–10 mapped to your roles; higher ranks inherit lower ones.
- A graceful close: the member sees a live countdown and can confirm or ask for more help.
- Transcripts you own: saved in your server; your messages are never stored on our side.
- Abuse controls: cooldowns, throttling, one open ticket per type, and a blocklist; panels also repair themselves if a button stops responding.
Installing
- Use the official invite link from the home page. You'll need the Manage Server permission to add it.
- Approve the requested permissions. It only asks for what it needs, and it does not request Administrator.
- The bot DMs the installer instructions. If you miss it, run
/setupanywhere in the server.
First-time setup
Run /setup. It's admin-only and 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 a path:
Quick setup ~2 min
Choose your staff role (it becomes rank 2, "Moderator"), 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, then publish the panel. Ends with a permissions check.
Custom setup
Set up several staff levels (e.g. Staff → rank 2, Managers → rank 4, Bot admins → rank 5), define multiple ticket types with their own handler and escalation roles, and write your own panel text.
You can re-run /setup any time. Once configured, an Adjust a section… menu jumps you straight to staff levels, channels, ticket types, or the panel.
Daily use
Members open tickets straight from a panel button, with nothing for them to memorize. They press a button, fill the short form (on by default, optional per type), and land in a private channel named after them and the type (like membername-bug) that opens with a welcome message and their answers. One open ticket per type, per member.
/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 (see Ticket types below).
Common commands and who can run them
| Command | Who | What it does |
|---|---|---|
/create user:@member [type] | rank 2+ | Open a ticket with a member (also via right-click → Apps → Open Modmail) |
/close | type's close rank (default 1) | Propose closure; member sees a countdown plus Confirm / "I need more assistance" |
/forceclose | rank 4+ | Close immediately, no member confirmation |
/reopen | rank 4+ | Reopen a closed ticket; the member regains access |
/archive | type's close rank (default 1) | Save the transcript to the archive channel, then delete the ticket channel |
/block · /unblock | rank 2+ | Stop / re-allow a member opening tickets |
/setup · /config · /panel · /diagnose | rank 5 / Admin | Set up and configure the bot; check permissions |
/data delete | Manage Server | Permanently erase all of this server's bot data (confirmation required) |
/support · /feedback · /bugreport | anyone | Support invite / message the developer (no message text is stored) |
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"; everything about it is yours to change under /config ticket:
| Command | What it does |
|---|---|
/config ticket add | New type; inherits channels and staff role from your first type |
/config ticket edit | Rename (name:), reposition (sort:, 1 = first = the /create and Open Modmail default), or change category, roles, archive channel, or button color |
/config ticket intake | Up to five questions members answer before the channel opens (45 characters each) |
/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 emoji · form · auto-archive | Button emoji, skip the intake form, or archive automatically after close |
/config ticket close-rank · archive-rank | Minimum staff ranks to close and to archive this type |
/config ticket remove | Deletes an unused type; disables one that has history |
After changing anything that shows on the panel (name, order, emoji, color), run /panel repair to re-render the buttons.
Permission tiers
Staff access is organized into ranks 1–10 that you map to your roles. Higher ranks inherit lower ones, and Discord Administrators bypass tier checks. These are the built-in minimums (override any of them with /config staff gate):
Default command minimums
| Command(s) | Minimum |
|---|---|
/close, /archive | the ticket type's close rank (default 1) |
/create, /block, /unblock | rank 2 |
/forceclose, /reopen | rank 4 |
/setup, /diagnose, /config, /panel | rank 5 (or Administrator) |
/data delete | Manage Server (not a staff tier, so it can't be delegated) |
Who can see a ticket follows the type's own audience: its channels and archive are visible to the type's configured roles (ping, view, and escalation) plus every staff tier at or above the lowest tier rank among those roles, and never below the type's close rank. A type handled only by rank-5 roles stays senior-only; a type pinging a rank-2 role is inherited by every higher tier. Raising a type's close rank restricts visibility further, and /config ticket archive-rank can set a higher rank just for archiving, a management-review step for who can archive and read a type's transcripts.
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 membername-bug-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.
- File limits scale with your server's Boost level: up to 50 MB/file at level 2, 100 MB at level 3, and up to 40 files or 100 MB per archive. Anything larger is listed by name, never silently dropped.
- Files that can run code (
.html,.svg) are re-uploaded with a.txtsuffix and flagged ⚠️.
Keep the archive channel staff-only, since transcripts can contain everything a member shared.
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 | Symptom if missing |
|---|---|---|
| View Channels | server-wide | Nothing works |
| Manage Channels | ticket category | "Ticket creation failed" after the form |
| Manage Roles | ticket category | 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 Roles (or mentionable roles) | ticket channels | Staff never pinged on new tickets |
Troubleshooting
| Problem | What to do |
|---|---|
| Buttons do nothing | Run /panel repair, then /diagnose. |
| "You already have an open ticket," but the channel is gone | An admin runs /config cleartickets user:@member. |
| Nobody was pinged | The ping role isn't mentionable by the bot. Make the role mentionable. |
| Archive failed | Usually Attach Files or Send Messages is missing in the archive channel; /diagnose will say so. |
| Staff commands fail inside tickets | A channel restriction in Server Settings → Integrations. See the FAQ; restrict by role, never by channel. |
| The bot shows Administrator | Inherited from a role attached to it; /diagnose names the role. See the FAQ. |
| Anything else | Run /bugreport; it goes to the developer (never your messages). |
FAQ
Can I have multiple panels?
Yes. One panel per channel, each with its own buttons.
Can members DM the bot to open a ticket?
No. Tickets start from a panel button only, and the bot doesn't read DMs by design.
Permission puzzles, update, and data questions live on the full FAQ.