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

# Emoji

> Headless has two emoji-related tools: copy custom emojis into a server and configure the bot's response emojis. They are different catalogs with different permissions.

> **Requirements**
>
> The member copying emojis needs **Manage Expressions** or an equivalent permission. Headless needs Manage Emojis and Stickers, and the server needs free slots.

> **Batches**
>
> Group items with `.emoji copy-batch`; review the final report because some copies can succeed while others fail.

> **Organization**
>
> Use clear names, avoid duplicates, and test with a small batch first.

> [!NOTE]
>
> Copying emojis into a server, editing the bot's global response styling, and managing the Headless visual pack are separate operations with different permissions and storage.

## Copy emojis into a server

`.emoji copy <emoji> [name]` and `.emoji copy-batch <emojis...>` require `Manage Emojis`. The bot needs permission to create emojis and available server capacity. Permission or quota failures are reported. Discord may label this permission `Manage Expressions`; `.emoji copy-batch` accepts `batch` and `multi`, while `.emoji copy` accepts `clonar` and `import`.

### Copy one emoji

```headless-command Syntax theme={null}
.emoji copy <emoji> [name]
```

```headless-command Example theme={null}
.emoji copy <:emoji_name:REAL_ID> name
```

### Copy a batch

```headless-command Syntax theme={null}
.emoji copy-batch <emojis>
```

```headless-command Example theme={null}
.emoji copy-batch <:first:REAL_ID> <:second:REAL_ID>
```

> [!NOTE]
>
> Replace `REAL_ID` and the example names with accessible custom-emoji markup copied from Discord. These are placeholders, not universal IDs.

## Bot response emojis

`/emoji view` requires `Manage Server`; `/emoji set` and `/emoji reset` require `Administrator`. Editable keys include success, error, warn, verified, brand, typing, log, log\_arrow, and log\_link. Changes apply at runtime and are saved in bot configuration; resetting all editable emojis preserves the Headless visual-pack mapping. `/emoji reset` accepts an optional key; without one, it resets all editable response emojis.

```headless-command Syntax theme={null}
/emoji view
```

```headless-command Example theme={null}
/emoji view
```

```headless-command Syntax theme={null}
/emoji set key:<key> emoji:<emoji>
```

```headless-command Example theme={null}
/emoji set key:success emoji:✅
```

```headless-command Syntax theme={null}
/emoji reset [key:<key>]
```

```headless-command Example theme={null}
/emoji reset key:success
```

## Valid inputs

Custom emojis must be accessible to the bot. Copy downloads the Discord asset and creates a copy in this server; it does not create a role assignment or preserve the original ID.

## Batches and names

Batch results list copied and failed emojis separately; a failure does not roll back successful copies. Start with a small batch, use clear valid names, avoid duplicates, and review the final report before retrying.

## Headless visual theme

`.emoji headless status` reports the theme state and available capacity in the current server. `install` installs the 24-emoji Core pack; `extend` adds up to 76 optional icons and permits a partial install when capacity runs out. The invoking member needs `Manage Emojis`, and the bot needs `Manage Emojis and Stickers`. The visual map is persisted bot-wide and records its installation server. `extend`, `rollback`, `refresh CONFIRMAR`, and `purge CONFIRMAR` are accepted only from that server. `rollback` restores generic mappings without deleting files; `refresh` replaces tracked PNGs; `purge` requires rollback first and deletes only IDs tracked by the pack. Red error X and yellow warnings remain protected.

> [!NOTE]
>
> Legacy installations without a saved `guild_id` reject maintenance for safety. Run `.emoji headless install` in the server that contains the pack to register its scope before using those commands.

```headless-command Syntax theme={null}
.emoji headless status
```

```headless-command Example theme={null}
.emoji headless status
```

```headless-command Syntax theme={null}
.emoji headless install
```

```headless-command Example theme={null}
.emoji headless install
```

```headless-command Syntax theme={null}
.emoji headless extend
```

```headless-command Example theme={null}
.emoji headless extend
```

```headless-command Syntax theme={null}
.emoji headless rollback
```

```headless-command Example theme={null}
.emoji headless rollback
```

```headless-command Syntax theme={null}
.emoji headless refresh [confirmation]
```

```headless-command Example theme={null}
.emoji headless refresh CONFIRMAR
```

```headless-command Syntax theme={null}
.emoji headless purge [confirmation]
```

```headless-command Example theme={null}
.emoji headless purge CONFIRMAR
```

## Theme maintenance

> **Rollback, refresh, and purge**
>
> `rollback` disables the theme and restores generic mappings without deleting assets. `refresh CONFIRMAR` deletes and recreates only emojis tracked by this pack. `purge CONFIRMAR` requires rollback and deletes only tracked IDs; if Discord rejects a deletion or an ID cannot be resolved, Headless retains that mapping so you can fix permissions or cache access and retry.

> **Pack scope**
>
> Theme state and mappings are stored bot-wide. `extend`, `rollback`, `refresh`, and `purge` compare the current server with the installation `guild_id` before changing state or emojis. If the ID is missing or does not match, the command exits without changes.

## Command reference

> **Complete command reference**
>
> * **`.emoji` (`.emojis`, `.em`)** — **Member permission:** Manage Emojis · **Result:** Shows the emoji-copy subcommands.
> * **`.emoji copy <emoji> [name]` (`clonar`, `import`)** — **Member permission:** Manage Emojis · **Result:** Copies an accessible emoji into the current server; Headless needs Manage Emojis and Stickers.
> * **`.emoji copy-batch <emojis>` (`batch`, `multi`)** — **Member permission:** Manage Emojis · **Result:** Attempts each copy and reports successes and failures separately; Headless needs Manage Emojis and Stickers.
> * **`.emoji headless` (`orange`, `tema`)** — **Member permission:** Manage Emojis · **Result:** Shows visual-pack help.
> * **`.emoji headless status`** — **Member permission:** Manage Emojis · **Result:** Reports pack status and remaining capacity in the current server.
> * **`.emoji headless install` (`apply`, `activar`)** — **Member permission:** Manage Emojis · **Result:** Installs the 24-emoji Core pack and enables it; Headless needs Manage Emojis and Stickers.
> * **`.emoji headless extend` (`extended`, `extras`)** — **Member permission:** Manage Emojis · **Result:** Installs up to 76 optional icons and may stage a partial install when capacity runs out.
> * **`.emoji headless refresh [confirmation]` (`update`, `actualizar`)** — **Member permission:** Manage Emojis · **Result:** Runs only with `CONFIRMAR`; replaces tracked PNGs. Headless needs Manage Emojis and Stickers.
> * **`.emoji headless rollback` (`disable`, `desactivar`, `generic`)** — **Member permission:** Manage Emojis · **Result:** Disables the pack and restores generic mappings without deleting PNGs.
> * **`.emoji headless purge [confirmation]`** — **Member permission:** Manage Emojis · **Result:** Requires rollback and `CONFIRMAR`; deletes only tracked IDs. Headless needs Manage Emojis and Stickers.
> * **`/emoji view`** — **Member permission:** Manage Server · **Result:** Reads current bot response-emoji keys.
> * **`/emoji set key:<key> emoji:<emoji>`** — **Member permission:** Administrator · **Result:** Changes one editable key and saves the bot-wide setting.
> * **`/emoji reset [key:<key>]`** — **Member permission:** Administrator · **Result:** Resets one key or all editable response emojis; the Headless visual pack mapping is preserved.

The prefix group is server-only. The `/emoji` routes are native application commands, not generic prefix bridges. Only installs and maintenance that create/delete emojis require the bot's Manage Emojis and Stickers permission; reads, rollback, and response-mapping updates do not grant the bot broader permissions.

## Steps

**1. Choose the task**

Use `.emoji copy` to import an emoji to the server, or `/emoji set` to change Headless response styling.

**2. Check permissions and quota**

Confirm Manage Emojis/Administrator for the selected command and available emoji capacity.

**3. Verify or reset**

Inspect the result; `/emoji reset key:<key>` restores the default for one editable key.

> [!WARNING]
>
> `refresh CONFIRMAR` and `purge CONFIRMAR` are destructive operations on tracked emojis. Check `.emoji headless status` first; the bot only runs these operations in the installation server and does not delete emojis outside the pack.

## Related pages

* [Reaction Roles](/docs/en/server/roles/reaction-roles.md)
* [Branding](/docs/en/server/branding.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.