> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celestia.rest/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Mute

> Prevent users from posting images in your server

## Overview

The Image Mute system lets moderators restrict a user from posting images and attachments across all channels. It works by assigning a dedicated role with deny overwrites applied to every channel, and by stripping any existing roles that grant image permissions — ensuring the mute cannot be bypassed through role stacking.

The system is persistent across restarts, supports timed mutes with automatic expiry, and re-applies the mute role if it is manually removed.

***

## Setup

Before using image mute, the system must be configured for your server. This creates the `Image Muted` role and applies deny overwrites to every text channel automatically.

<Warning>
  Setup requires **Administrator** permission and grants Celestia **Manage Roles** and **Manage Channels**. These are needed to apply the role and configure channel overwrites.
</Warning>

```bash theme={null}
,imute setup
```

To completely remove the image mute system, restore all muted users, and delete the role:

```bash theme={null}
,imute reset
```

<Note>
  Reset will unmute every currently muted user and restore their stripped roles before deleting the `Image Muted` role.
</Note>

***

## Commands

<AccordionGroup>
  <Accordion title="imagemute" icon="image">
    Apply an image mute to a user, optionally with a duration and reason.

    <CodeGroup>
      ```bash Syntax theme={null}
      ,imute <user> [duration] [reason]
      ,imute setup
      ,imute reset
      ```

      ```bash Example theme={null}
      ,imute @user
      ,imute @user 7d Posting NSFW images
      ,imute @user 1h Spamming memes
      ,imute setup
      ,imute reset
      ```
    </CodeGroup>

    **Aliases:** `imute`
    **Permissions:** Moderate Members
    **Setup permissions:** Administrator
  </Accordion>

  <Accordion title="imageunmute" icon="image">
    Remove an image mute from a user and restore their previously stripped roles.

    <CodeGroup>
      ```bash Syntax theme={null}
      ,iunmute <user> [reason]
      ```

      ```bash Example theme={null}
      ,iunmute @user
      ,iunmute @user Appealed successfully
      ```
    </CodeGroup>

    **Aliases:** `iunmute`
    **Permissions:** Moderate Members
  </Accordion>
</AccordionGroup>

***

## Duration Format

Timed mutes automatically expire and restore the user's roles when the duration runs out. The following time units are supported:

| Unit    | Examples                    |
| ------- | --------------------------- |
| Seconds | `30s`, `30sec`, `30seconds` |
| Minutes | `10m`, `10min`, `10minutes` |
| Hours   | `2h`, `2hr`, `2hours`       |
| Days    | `7d`, `7day`, `7days`       |
| Weeks   | `1w`, `1week`, `1weeks`     |

```bash theme={null}
,imute @user 30m Temporarily restricted
,imute @user 7d Repeated image spam
,imute @user 1w Posting disallowed content
```

Omitting a duration creates a permanent mute that must be removed manually with `iunmute`.

***

## How It Works

<Steps>
  <Step title="Role creation">
    `imute setup` creates an `Image Muted` role and applies `AttachFiles: false` and `EmbedLinks: false` overwrites to every text channel in the server.
  </Step>

  <Step title="Role stripping">
    When a mute is applied, any roles the user holds that grant image permissions (attach files, embed links, or administrator) are stripped and saved for later restoration.
  </Step>

  <Step title="Mute role assigned">
    The `Image Muted` role is added to the user, enforcing the channel-level deny overwrites.
  </Step>

  <Step title="Enforcement">
    If someone manually removes the `Image Muted` role or grants the user an image-permission role while muted, Celestia automatically re-applies the mute and strips the offending role.
  </Step>

  <Step title="Unmute and restore">
    On manual unmute or expiry, the user's previously stripped roles are restored and the `Image Muted` role is removed.
  </Step>
</Steps>

***

## Role Stripping

To prevent mute bypasses, the system strips any role that grants image posting permissions at the guild or channel level. This includes roles with:

* `Attach Files`
* `Embed Links`
* `Administrator`

These roles are saved per-user and restored automatically on unmute.

<Warning>
  If a stripped role is deleted while the user is muted, it cannot be restored. The unmute response will list any roles that could not be returned.
</Warning>

***

## Persistence and Enforcement

The system actively enforces mutes beyond just role assignment:

* **Startup recovery** - On bot restart, mutes stored in the database are re-applied to any users missing the role, and any image-permission roles gained while the bot was offline are stripped.
* **Manual removal prevention** - If the `Image Muted` role is manually removed from a user by a moderator or admin, Celestia will immediately re-add it.
* **Role grant prevention** - If a muted user is given a role that grants image permissions, that role is automatically stripped.
* **New channel sync** - Any new channel created while the system is active automatically receives the correct overwrites for the `Image Muted` role.

***

## Mod Log Integration

Every image mute and unmute action is recorded as a mod case. Logs include:

* The acting moderator
* The target user
* The reason provided
* The duration (if timed)

Automatic expiry unmutes are logged with Celestia as the actor and `Image mute duration expired` as the reason.

***

## Hierarchy Requirements

<CardGroup cols={2}>
  <Card title="Bot role position" icon="robot">
    Celestia's role must be above any role it needs to strip or assign. Roles above Celestia cannot be stripped.
  </Card>

  <Card title="Moderator position" icon="shield">
    You cannot image mute a user whose highest role is equal to or above your own highest role.
  </Card>
</CardGroup>

<Note>
  The server owner cannot be image muted.
</Note>