# Moderation commands

> Make /kick, /ban, /timeout and /purge for your moderators, with a permission check and a log message.

You will make four commands for your moderators:

| Command | What it does |
|---|---|
| `/kick` | Removes a member from the server. They can join again. |
| `/ban` | Removes a member and stops them from joining again. |
| `/timeout` | Stops a member from talking for a while. |
| `/purge` | Deletes many recent messages at once. |

Each one checks that the member who runs it is allowed to, and posts a note in a log channel.

## Before you start

Make a text channel named `mod-log`. The commands post there.

Check that the bot's role is **above** the roles of the members it acts on. Move it up under **Server Settings → Roles**. Discord never lets a bot act on the server owner.

## Two layers of protection

Use both:

1. **Hide the command.** In the command form, switch to **Advanced**. Open **Permissions** and pick a permission under **Discord permissions**, for example **Kick Members**. Discord then hides the command from members without it.
2. **Check in code.** `require_permission("kick_members")` stops the command if the member lacks the permission. Server admins can change the hiding in Discord's own settings, so the code check is the one you can trust.

If the member does not have the permission, `require_permission` stops the command and shows an error. You can write your own text with `error_message="..."`.

## /kick

Create a slash command named `kick` with two arguments:

| Type | Name | Required |
|---|---|---|
| Member | `target` | Yes |
| Text | `reason` | No |

**Pre-hook:**

```python
require_permission("kick_members")

if target.id == user.id:
    set_error("You can't kick yourself.")

why = reason or "No reason given"
kick_member(target, reason=why)
send_message("mod-log", f"👢 {user.mention} kicked {target.mention}. Reason: {why}")
set_content(f"Kicked {target.display_name}.")
```

`set_error` stops the command and shows the text to the member. Nothing after it runs.

## /ban

Same arguments as `/kick`.

**Pre-hook:**

```python
require_permission("ban_members")

if target.id == user.id:
    set_error("You can't ban yourself.")

why = reason or "No reason given"
ban_member(target, reason=why)
send_message("mod-log", f"🔨 {user.mention} banned {target.mention}. Reason: {why}")
set_content(f"Banned {target.display_name}.")
```

## /timeout

| Type | Name | Required | Description |
|---|---|---|---|
| Member | `target` | Yes | Who to time out |
| Text | `length` | Yes | For example 10 minutes, 1 hour, 2 days |

**Pre-hook:**

```python
require_permission("moderate_members")

timeout_member(target, length)
send_message("mod-log", f"🔇 {user.mention} timed out {target.mention} for {length}.")
set_content(f"Timed out {target.display_name} for {length}.")
```

A timeout can be up to **28 days**. A longer time, or a time the bot cannot read, stops the command with an error.

To lift a timeout early, make `/untimeout` with `remove_timeout(target)`.

## /purge

| Type | Name | Required | Description |
|---|---|---|---|
| Integer | `amount` | Yes | How many messages to delete |

**Pre-hook:**

```python
require_permission("manage_messages")

if amount < 1 or amount > 100:
    set_error("Pick a number from 1 to 100.")

purge_messages(channel.id, amount)
send_message("mod-log", f"🧹 {user.mention} deleted {amount} messages in {channel.mention}.")
set_content(f"Deleted {amount} messages.")
```

Under **Behavior**, turn on **Only the user sees the reply**. Otherwise the reply lands in the channel you just cleaned.

> **Watch out:** Discord only bulk-deletes messages newer than **14 days**. Older messages are skipped. The bot needs **Manage Messages** and **Read Message History** in that channel.

## Permissions the bot needs

| Command | The bot needs |
|---|---|
| `/kick` | Kick Members |
| `/ban` | Ban Members |
| `/timeout` | Timeout Members |
| `/purge` | Manage Messages, Read Message History |

If the bot lacks one, the member sees an error like *"Missing permission to kick member"*.

## Limits

Each command sends one log message. A free server can send **3** extra messages per run, so you have room to spare. See [Limits](https://ccbot.app/docs/concepts/limits).

## Learn more

- [Checks](https://ccbot.app/docs/reference/checks) lists `require_permission`, `allowed_roles`, `cooldown` and the other gates.
- [Members and roles](https://ccbot.app/docs/reference/members-and-roles) lists `kick_member`, `ban_member`, `timeout_member` and more.
- [Auto moderation](https://ccbot.app/docs/guides/auto-moderation) handles spam and scam links without a moderator.