Modmail Moderator Guide

Overview

The Modmail system allows users to contact server staff privately by sending direct messages (DMs) to the bot. Each conversation is organized in a dedicated thread within your server's modmail channel, creating a private, trackable communication channel between users and staff.

How Modmail Works

For Users

1. Users DM the bot to start a conversation
2. If modmail is enabled in multiple servers, users will see a dropdown menu to select which server they want to contact
3. The support server (if configured) appears first in the dropdown with a special indicator (🛟)
4. A new thread is automatically created in your modmail channel
5. Users can send messages, images, and files through DM
6. All messages are forwarded to the modmail thread where staff can see and respond
7. Rate limiting is handled automatically - users don't need to worry about message delivery delays

For Moderators

1. New modmail threads appear in your configured modmail channel
2. Each thread represents one user conversation
3. Staff can respond directly in the thread
4. Responses are automatically forwarded to the user's DMs
5. Threads can be closed when the conversation is resolved

Key Features

⚡ Rate Limiting Integration

• All modmail operations automatically use the rate limiting system
• Prevents Discord API rate limit errors for reliable message delivery
• Messages are queued and sent automatically when rate limits allow
• No configuration needed - works automatically in the background
• Staff can monitor rate limiting statistics using /ratelimitstatus if needed

📬 Automatic Thread Creation

• When a user first contacts modmail, a new thread is automatically created
• Thread names follow the format: username-userid (e.g., JohnDoe-123456789)
• Threads are set to auto-archive after 7 days of inactivity
• Each thread includes an initial embed with user information

🔄 Bidirectional Communication

• User → Staff: Messages sent via DM are forwarded to the modmail thread
• Staff → User: Messages sent in the thread are forwarded to the user's DMs
• All messages include timestamps and are formatted in easy-to-read embeds

📎 File & Image Support

• Users can send images, files, and attachments through DM
• Images are automatically embedded in the modmail thread
• File attachments are linked for easy access
• Staff can also send images and files through the thread

🎯 Multi-Server Support

• The bot supports modmail across multiple servers
• Users in multiple servers with modmail enabled will see a dropdown menu to select which server they want to contact
• Support server (ID: 1431420578434256981, if configured) is always shown first with a special indicator 🛟 for easy access
• The dropdown makes it easy for users to choose the correct server when they're members of multiple communities
• User selection is remembered for the duration of their modmail session

Moderator Workflow

1. Receiving a New Modmail

When a user first contacts modmail, you'll see:

1. Initial Thread Message: An embed showing:
   • User's display name and mention
   • User ID (for reference)
   • Account creation date
   • User's avatar
2. User's First Message: The user's message will appear as an embed with:
   • Message content
   • Attachments (if any)
   • Timestamp
   • User information
3. User Notification: The user receives a welcome message explaining:
   • Their message has been forwarded to staff
   • How to continue the conversation
   • That messages are anonymous to other members

2. Responding to Users

To reply to a user:

1. Navigate to the modmail thread in your modmail channel
2. Simply type your message and send it
3. Your message will automatically be forwarded to the user's DMs
4. The bot will add a ✅ reaction to confirm the message was sent

Tips for Responding:

• Be clear and professional
• Use embeds naturally (the bot handles formatting)
• You can include images and files - they'll be forwarded to the user
• Multiple staff members can participate in the same thread

3. Handling Follow-up Messages

• Subsequent messages from the user will appear in the same thread
• You don't need to do anything special - just respond as needed
• The thread stays active until manually closed or archived

4. Closing a Modmail Thread

When a conversation is resolved, close the thread:

Using the Command:

What happens when you close:

• The thread is archived and locked
• The user receives a notification that the thread has been closed
• If you provided a reason, it's included in the notification
• The thread mapping is cleaned up from the system
• The user can start a new thread by sending another DM

Permissions Required:

• You need Manage Threads permission to close modmail threads

Example:

Thread Information

Each modmail thread contains:

Initial Thread Embed

• Title: "📬 New Modmail Thread"
• User Information: Display name, mention, and User ID
• Account Created: Relative time (e.g., "2 years ago")
• Thumbnail: User's avatar

Message Embeds

From User (appears in thread):

• Title: "📥 Message from User"
• Author: User's name and ID
• Content: The actual message text
• Attachments: Links and embedded images
• Timestamp: When the message was sent

From Staff (sent to user's DM):

• Title: "📨 Message from Staff"
• Author: "Staff from [Server Name]"
• Content: Your message text
• Attachments: Links and embedded images
• Footer: "Reply to this DM to continue the conversation"
• Timestamp: When the message was sent

Permissions Required

For Moderators/Staff

To use modmail effectively, you need:

• View Channel: Access to the modmail channel
• Send Messages: To respond to users
• Embed Links: For message formatting
• Attach Files: To send images/files
• Read Message History: To see conversation history
• Manage Threads: To close modmail threads (optional but recommended)
• Send Messages in Threads: To respond in threads

For the Bot

The bot requires:

• View Channels: Access to modmail channel
• Send Messages: In modmail channel and threads
• Embed Links: For formatted messages
• Attach Files: For forwarding attachments
• Manage Threads: To create and archive threads
• Read Message History: To track conversations
• DM Messages Intent: Enabled in Discord Developer Portal (already configured)

Best Practices

Communication

✅ Do:

• Respond promptly to modmail inquiries
• Be professional and courteous
• Use clear, concise language
• Provide helpful information
• Close threads when resolved

❌ Don't:

• Share personal information in threads (users can see who responds)
• Leave threads open indefinitely
• Use modmail for casual conversation
• Delete modmail threads (use /closemodmail instead)

Thread Management

• Close threads promptly when issues are resolved
• Use the reason field when closing for documentation
• Coordinate with team if multiple staff are responding
• Don't manually delete threads - use the close command to properly notify users

Privacy

• Remember that multiple staff members can see modmail threads
• Users cannot see who specifically responded, only that "Staff from [Server]" replied
• All conversations are logged in the thread for review
• Keep sensitive information secure

Troubleshooting

User Can't Send Messages

Issue: User reports they can't contact modmail

Solutions:

• Verify modmail is enabled for your server (admin configuration)
• Check that the bot is online and operational
• Ensure the user has DMs enabled (users with DMs disabled cannot use modmail)
• Verify the modmail channel still exists and is accessible

Messages Not Forwarding

Issue: Staff messages aren't reaching users

Possible Causes:

• User has DMs disabled or blocked the bot
• Bot doesn't have permission to send DMs
• User has left the server

What You'll See:

• Error message in thread: "❌ Cannot send DM to user. They may have DMs disabled."
• ✅ reaction won't appear on your message

Solutions:

• Inform user they need to enable DMs from server members
• Ask user to check their privacy settings
• Consider alternative contact methods if urgent

Thread Already Closed

Issue: Trying to close an already-archived thread

What Happens:

• The command will acknowledge the thread is already closed
• Configuration is still cleaned up
• User won't receive duplicate notifications

Can't Find a User's Thread

Issue: Looking for a specific user's modmail thread

Solutions:

• Search for the user's name or ID in the modmail channel
• Thread names include the user ID for easy searching
• Check if the thread was already closed/archived
• Verify you're looking in the correct modmail channel

Multiple Threads for Same User

Issue: User has multiple active threads

Why This Happens:

• Rarely occurs, but can happen if:
  • Thread was deleted manually
  • Configuration issue
  • User was in multiple servers

Solution:

• Close all threads for the user
• User's next DM will create a fresh thread
• Report persistent issues to bot administrator

Command Reference

/closemodmail

Close the current modmail thread.

Usage:

Parameters:

• reason (optional): Reason for closing the thread. This will be included in the notification sent to the user.

Permissions:

• Requires Manage Threads permission
• Can only be used in modmail threads

Example:

What It Does:

1. Archives and locks the thread
2. Sends closure notification to user (if DMs enabled)
3. Removes thread from active tracking
4. Allows user to start new thread if needed

Configuration (Administrator Only)

Modmail must be configured by a server administrator. Configuration includes:

• Modmail Channel: Where threads are created
• Enable/Disable: Toggle modmail for the server
• Category (optional): Create threads in specific category

Configuration is stored in config.json under the modmail section for each guild.

Note: Contact your server administrator if modmail isn't working or needs configuration changes.

Support & Questions

If you encounter issues or have questions about using modmail:

1. Check this guide first
2. Verify your permissions
3. Contact your server administrator
4. Check if the bot is online and functioning

Quick Reference

Examples

Example 1: Handling a User Question

User's DM:

In Modmail Thread: You'll see an embed with the user's message.

Your Response: Simply type in the thread:

This automatically forwards to the user's DMs.

Example 2: Closing a Thread

When conversation is resolved:

What user sees: A DM notification saying their modmail thread has been closed with your reason included.

Example 3: Multi-Message Conversation

User: "I lost access to a channel"

Staff Member 1: "Let me check your roles..."

Staff Member 2: "I've restored your access. Try now!"

User: "It works! Thank you!"

Staff Member 1: "Great! Let me close this thread."