Modmail

Modmail is a relay between your members and your staff. A member DMs Phantom; their message lands in a private staff thread. Staff reply in the thread; the reply arrives in the member's DMs.

Each conversation is one modmail thread. A member has at most one open thread per server at a time — every DM they send while a thread is open relays to the same staff thread.

Setup

1. Open Dashboard → Modmail.
2. Pick a staff channel — every new modmail will open a private thread (or private channel) under it.
3. Pick a mode:
   • Discord Threads (recommended) — Phantom creates a private thread per modmail. Lighter weight, automatic archiving.
   • Private channels — Phantom creates a fresh text channel per modmail under the chosen category. Use this if your community prefers the channel-list visibility.
4. (Optional) Set an auto-responder, ping roles, and auto-close cadence.
5. Toggle Enabled.

Required bot permissions in the staff channel:

• View Channel, Send Messages, Manage Webhooks (always — Manage Webhooks lets the relay show each member's username and avatar)
• Create Private Threads, Send Messages in Threads (thread mode)
• Manage Channels (private-channel mode — to create the per-modmail channel)

How a thread opens

1. A member DMs Phantom.
2. Phantom checks which of your servers the member belongs to and which of those have modmail enabled.
3. If there's exactly one match, Phantom opens a thread there. If there's more than one, Phantom picks one consistently so subsequent DMs from that member always land in the same place. (An explicit "which server?" prompt is coming.)
4. The thread shows up in your staff channel with a context card — the member, when they joined the server, and your configured role ping.
5. The member receives the auto-responder DM if one is configured.
6. The bot adds ✅ to the member's DM to confirm it landed.

From that point on:

• Every DM the member sends shows up in the staff thread under their own username and avatar so staff can see who's writing at a glance.
• Every message a staff member writes in the staff thread is delivered as a DM to the member. With Anonymous staff replies on (default), the DM comes from Phantom; with it off, it's prefixed with the staff member's name.

Closing

Staff can close a thread three ways:

• /pmodmail close [reason] in the thread.
• The Force close button on Dashboard → Modmail → Threads.
• Automatically, if Auto-close after inactivity is set and no one has written in either direction for that long.

On close:

• The member receives a short close DM with the optional reason.
• The staff thread is locked and archived (thread mode) or left intact (channel mode).
• If a Transcript channel is configured, Phantom posts a link there so the conversation stays easy to find.

Slash commands

Command	What it does
/pmodmail close [reason?]	Close the current thread. The reason is DM'd to the member.
/pmodmail claim	Mark yourself as the owner so other staff know it's covered.
/pmodmail unclaim	Release your claim.
/pmodmail block [@user?]	Block a member from opening modmail (defaults to this thread's member).
/pmodmail unblock @user	Unblock.

Anyone with Manage Messages or Administrator can run these. If you've set up team roles, granting the Modmail "edit" permission works too.

Privacy

• Anonymous staff replies (on by default): the member only sees "Phantom" as the sender — they don't see which staff member replied.
• The staff thread always shows the staff member's name so other staff can tell who's working the thread.
• The dashboard transcript shows both sides of the conversation and is only visible to users with the Modmail "view" permission.

Rate limits

To keep things sane:

• A member can open at most one new modmail thread every 5 minutes.
• Inside an open thread, each side can send up to 10 messages per minute. Above that, the message is held back and the bot reacts ⏱️ — the next message a minute later goes through normally.

Webhooks (outbound events)

Event	When it fires
modmail.thread.opened	A new thread opens (one event per member contact, not per relay).
modmail.thread.closed	A thread closes — manual, auto, or from the dashboard.

Subscribe via Developer → Webhooks.

Troubleshooting

Symptom	What to check
Member DMs the bot, nothing happens	Is modmail enabled? Does the bot have the staff-channel permissions listed above? Is the member blocked?
Staff replies aren't reaching the member	The member has DMs from server members disabled, or has left every server you share with Phantom. The bot reacts ❌ on the staff message and posts a one-line note in the thread when this happens.
Thread opened but the staff channel didn't ping	The configured ping roles ping on the first message of a new thread only, not on every reply.
Member is in multiple modmail-enabled servers — the wrong one got it	Until the explicit server picker lands, route each member to a specific server by keeping modmail enabled in only one of the servers you share with them — or use distinct custom bots per server so each member only DMs the bot for the right server.