> ## 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.

# Reaction Roles

> Configure safe message-reaction role assignments for your server.

> [!NOTE]
>
> The person configuring it needs `Manage Roles` and must be the server owner, Headless owner, or an authorized Anti-Nuke Admin. Headless also needs `Manage Roles`, a higher role position, and `View Channel`, `Read Message History`, and `Add Reactions` in the message channel.

## Configure an assignment

**1. Prepare a dedicated role**

Do not use `@everyone`, Discord-managed roles, or roles with administrator or moderation permissions. The role must sit below the Headless role.

**2. Copy the message link**

The message must belong to the current server. Headless must be able to view the channel, read its history, and add reactions. Unicode and custom emojis are supported.

**3. Create and test the rule**

Run `.reactionrole add <message_link> <emoji> <role>`. Headless validates the values, adds the initial reaction, and saves the rule. Creating a new valid rule also enables Auto Role if it was off. Verify the assignment with a test account.

> [!NOTE]
>
> `.autorole on` enables the Auto Role configuration; it does not change the global module switch in Dashboard → Modules. A new rule also enables the configuration, but processing remains paused while the global switch is off.

### `.reactionrole add`

```headless-command Syntax theme={null}
.reactionrole add <message_link> <emoji> <role>
```

```headless-command Example theme={null}
.reactionrole add https://discord.com/channels/<server-id>/<channel-id>/<message-id> ✅ @Member
```

### `.reactionrole list`

```headless-command Syntax theme={null}
.reactionrole list
```

```headless-command Example theme={null}
.reactionrole list
```

### `.reactionrole remove`

```headless-command Syntax theme={null}
.reactionrole remove <message_link> <emoji>
```

```headless-command Example theme={null}
.reactionrole remove https://discord.com/channels/<server-id>/<channel-id>/<message-id> ✅
```

### `.reactionrole reset`

```headless-command Syntax theme={null}
.reactionrole reset [confirmation]
```

```headless-command Example theme={null}
.reactionrole reset confirm
```

### `.reactionrole removeall`

```headless-command Syntax theme={null}
.reactionrole removeall <message_link>
```

```headless-command Example theme={null}
.reactionrole removeall <copied_message_link>
```

Replace the placeholder with the URL Discord copies through **Copy Message Link**. The server, channel, and message IDs must each contain 17–20 digits, and the server must match the current one.

> [!WARNING]
>
> When a member removes the reaction, Headless removes the linked role from that member, even if they received it another way. Use a dedicated, low-risk role. Removing the configuration does not revoke roles already assigned or remove normal message reactions; clean those up separately if needed.

> **Limits and validation**
>
> Each server supports up to 100 rules and each message supports 20. The message+emoji pair must be unique, and each role can only be linked once per server. Links must include server, channel, and message IDs and belong to the current server. Headless rejects roles it cannot manage and skips bot events, missing rules, deleted roles, and repeated events. Raw events also handle messages that are no longer cached. Reactions that existed before the rule are not synchronized.

> **Pausing, storage, and related commands**
>
> These rules belong to Auto Role: `.autorole off` also pauses their processing. Use `.autorole on` to re-enable the module; creating a new valid rule also enables Auto Role if it was off. Rules are stored in the existing per-server PostgreSQL Auto Role configuration and require no schema migration. The group also accepts `.reactionroles`; `.rr` is reserved for role restoration. `remove` deletes one assignment, `removeall` deletes those for one message, and `reset confirm` deletes every assignment in the server. Confirmation is case-insensitive.

## Related pages

> **[Auto roles](/docs/en/server/roles/auto.md)**
>
> Review the module that enables and pauses reaction assignments.

> **[Self-assignable roles](/docs/en/server/roles/self-assignable.md)**
>
> Compare reaction rules with the self-assignable role panel.

> **[Headless permissions](/docs/en/permissions.md)**
>
> See the native and virtual permissions Headless can check.


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