Appeals
Let banned users appeal, review appeals with your staff and unban automatically on approval.
Appeals gives banned users a way to ask to come back. They answer your questions on a web page or in a Discord form, staff review the appeal in a private channel, and approving it unbans the user and tells them.
How It Works
- A member is banned. If Send Appeal Button When Banned is on, the ban DM includes an Appeal My Ban button.
- The user presses it, signs in with Discord on the appeal page and fills in the form.
- The appeal shows up in the Review Channel with Approve, Deny and Deny and Block buttons. Medusa can also open a thread for staff to discuss it.
- A reviewer picks a decision and writes the reason the user will see.
- Approving unbans the user and DMs them the result. If you set an Invite Channel for Approved Appeals, the DM includes a one-time invite. Denying DMs the reason. Deny and Block also stops the user from appealing again.
Reaching Banned Users
Discord does not let a bot DM or receive button presses from users who share no server with it, so there are two ways in.
The ban DM button links to a web page that Medusa hosts on its API. Bans made with the Moderation module add the button to the punishment DM, which is sent before the ban. Bans made any other way get a separate DM when Discord allows it.
You can also run a separate appeal server that banned users can still join. Pick it as the Appeal Server, choose a Panel Channel, then post the Appeals panel from the dashboard Post page or with /post in your main server. The panel button opens the appeal form inside Discord.
Web Appeal Page
The page lives at <API URL>/api/modules/appeals/appeal. Users sign in with Discord (only the identify scope) and answer the same questions as the Discord form. A decision DM often cannot reach a banned user, so opening the link again shows their latest appeal: pending, denied with the reason and any cooldown, or approved with the reason and the invite.
To set it up:
- Set
SERVER.API.URLinconfig.jsonto a public address banned users can reach. - Add your Discord client ID and client secret in the dashboard settings.
- In the Discord Developer Portal, add
<API URL>/api/modules/appeals/appealas an OAuth2 redirect.
Without a client ID and secret the page shows a setup notice instead of the form. Sign-in links expire after 15 minutes and the form after 30 minutes.
Limits
A user can only have one pending appeal, and only users who are banned can appeal. Days Between Appeals sets the wait after a denied appeal (0 turns it off). Maximum Appeals per User is a lifetime limit (0 means no limit).
Settings
Appeal Settings
| Setting | Default | What it does |
|---|---|---|
| Accept Ban Appeals | On | Turns appeals on or off. |
| Review Channel | None | Where new appeals are posted. |
| Reviewer Role | None | Role that can review appeals. |
| Mention Reviewers on New Appeals | On | Pings the reviewer role on each appeal. |
| Create Staff Discussion Thread | On | Opens a thread under each appeal. |
| Require a Reason for Decisions | Off | Reviewers must write a reason. |
| Send Appeal Button When Banned | On | Adds the appeal button to the ban DM. |
| Direct Message Decisions | On | DMs the user the decision. |
| Invite Channel for Approved Appeals | None | Channel used for the one-time invite. |
| Days Between Appeals | 7 | Wait after a denied appeal. |
| Maximum Appeals per User | 3 | Lifetime appeal limit. |
Appeal Questions: the form title and up to five questions. Each question has a label, a placeholder, a short or paragraph style and a required toggle.
Appeal Panel: the appeal server, panel channel, panel embed, button label and button emoji. In the embed, %guild% is the server being appealed.
Commands
| Command | What it does |
|---|---|
/appeals view <id> | Show an appeal with its answers and decision. |
/appeals approve <id> [reason] | Approve, unban and notify the user. |
/appeals deny <id> [reason] | Deny and notify the user. |
/appeals history <user> | List a user's appeals and whether they are blocked. |
/appeals block <user> | Stop a user from appealing. |
/appeals unblock <user> | Let a blocked user appeal again. |
/appeals belongs to the Moderator rank by default. Anyone with the Reviewer Role, the Ban Members permission or the Appeals ( Manage ) permission can use the review buttons.
The Appeals dashboard page lists every appeal with its status and reviewer. The Appeal Events log records submissions and decisions.