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

# Auto roles

> Auto Role combines join-time assignments, pre-verification roles, and member self-service role selectors. Configuration is stored per server. Commands edit that configuration; they do not backfill members who were already in the server.

Headless's Auto Role interface uses English by default. When configuration is loaded, only text that exactly matches a previous built-in default is updated; server-customized copy is preserved.

## Join-time assignment

The module is disabled by default. When enabled, it assigns the configured bot role to bot accounts; people receive the human role and, when configured, the temporary Pending Verify role. The default delay is 2 seconds. `delay` accepts an integer from 0 to 86,400 seconds; out-of-range values are clamped. The handler skips members with a configured exempt role, roles they already have, and roles Headless cannot manage.

### `.autorole`

```headless-command Syntax theme={null}
.autorole
```

```headless-command Example theme={null}
.autorole
```

### `.autorole human`

```headless-command Syntax theme={null}
.autorole human [role]
```

```headless-command Example theme={null}
.autorole human @Member
```

### `.autorole bot`

```headless-command Syntax theme={null}
.autorole bot [role]
```

```headless-command Example theme={null}
.autorole bot @Bot
```

### `.autorole delay`

```headless-command Syntax theme={null}
.autorole delay <seconds>
```

```headless-command Example theme={null}
.autorole delay 30
```

## Verify and pending roles

Verify's built-in panel uses English default titles, messages, and button labels. When reading older settings, Headless converts only values that exactly match the former built-in defaults; custom text—including Spanish copy—is preserved.

Headless's Verify flow assigns the roles configured in Verify and removes Auto Role's Pending Verify role where applicable. Although `.autorole verified @Role` saves a `verified_role_id`, the current Verify handler does not call the function that applies that field; do not rely on this setting to grant the verified role. Configure the final access role in Verify until that integration changes.

> [!NOTE]
>
> The public Verify button also rejects `@everyone`, Discord-managed roles, and roles with administrative or moderation permissions. If the configuration contains one, Headless skips it and notifies the member; an administrator must select a safe role in Verify.

### `.autorole pending`

```headless-command Syntax theme={null}
.autorole pending [role]
```

```headless-command Example theme={null}
.autorole pending @Pending
```

### `.autorole verified`

```headless-command Syntax theme={null}
.autorole verified [role]
```

```headless-command Example theme={null}
.autorole verified @Verified
```

## Panels and shared module switch

Auto Role also gates self-service selectors and Reaction Roles. `off` pauses join assignments and interactions for those flows, but keeps their saved rules and panels. Creating a group with `group`, publishing with `panel`, or adding a Reaction Role mapping can set `enabled` back to `true`; check the module state after those changes. Groups support up to 8 per server and 20 roles per group; see the self-service panel guide for their behavior.

> [!NOTE]
>
> Auto Role's saved `enabled` setting is separate from the global switch in Dashboard → Modules. If the global switch is off, join assignments, panels, and Reaction Roles stay paused even when `.autorole on` enables the configuration.

### `.autorole on`

```headless-command Syntax theme={null}
.autorole on
```

```headless-command Example theme={null}
.autorole on
```

### `.autorole off`

```headless-command Syntax theme={null}
.autorole off
```

```headless-command Example theme={null}
.autorole off
```

### `.autorole panel`

```headless-command Syntax theme={null}
.autorole panel [channel]
```

```headless-command Example theme={null}
.autorole panel #roles
```

### `.autorole group`

```headless-command Syntax theme={null}
.autorole group <name> [roles]...
```

```headless-command Example theme={null}
.autorole group colors @Red @Blue
```

### `.autorole title`

```headless-command Syntax theme={null}
.autorole title <title>
```

```headless-command Example theme={null}
.autorole title Choose your roles
```

### `.autorole message`

```headless-command Syntax theme={null}
.autorole message <message>
```

```headless-command Example theme={null}
.autorole message Select a role
```

### `.autorole thumbnail`

```headless-command Syntax theme={null}
.autorole thumbnail [url]
```

```headless-command Example theme={null}
.autorole thumbnail https://example.com/roles.png
```

### `.autorole image`

```headless-command Syntax theme={null}
.autorole image [url]
```

```headless-command Example theme={null}
.autorole image https://example.com/banner.png
```

### `.autorole gif`

```headless-command Syntax theme={null}
.autorole gif [url]
```

```headless-command Example theme={null}
.autorole gif https://example.com/roles.gif
```

> [!WARNING]
>
> `verified` currently saves the selection, but the Verify flow does not apply that field. Do not treat it as an active role grant; assign the final role through the actual Verify settings. Self-service selectors are voluntary, so never include sensitive permissions in those roles.

**Note:**

The initial delay is 2 seconds, and assignment depends on the server's `enabled` setting. The bot stores the last assignment error for troubleshooting; Discord permissions and hierarchy still apply.

## Dashboard, permissions, and data

In Dashboard → Roles → Auto Role you can edit roles, delay, exempt roles, panel title and copy, media, and groups. Commands use the server's configured prefix (period by default), and `.arole` aliases `.autorole`. You must run them in a server, have `Manage Roles`, and be the server owner, Headless owner, or a configured Anti-Nuke Admin. Headless also needs `Manage Roles`; Discord only lets it assign roles below the bot's highest role. Persistent configuration remains isolated per server in the existing Auto Role store.

## Steps

**1. Confirm who can manage the module**

Make sure your account passes the group authorization and has `Manage Roles`. Give Headless `Manage Roles` and place its role above every role it must grant or remove.

**2. Configure roles and exemptions**

In Dashboard → Roles → Auto Role, choose separate roles for people, bots, and Pending Verify; set the delay and exempt roles. Configure final verification roles in Verify.

**3. Enable and test the join event**

Run `.autorole on` and test with an account that joins after the change. Check status with `.autorole`; existing members are not assigned retroactively.

> **Registered prefix commands**
>
> Group and alias: `.autorole` / `.arole`. Without a subcommand, it displays status. Subcommands: `on` (`enable`, `activar`), `off` (`disable`, `desactivar`), `human` (`humans`, `humano`, `h`), `bot` (`bots`, `b`), `pending` (`pendiente`, `pend`, `p`), `verified` (`verify`, `verificado`, `v`), `delay` (`wait`, `espera`, `d`), `panel` (`sendpanel`, `selfroles`, `roles`), `group` (`grupo`, `colors`, `colores`), `title` (`titulo`), `message` (`mensaje`, `msg`), `thumbnail` (`thumb`), `image` (`banner`, `imagen`), and `gif`. These are prefix commands, not slash commands.

> **What disabling or clearing a role means**
>
> `.autorole off` does not delete configuration or panel messages, but the runtime stops processing join assignments, selectors, and reactions while Auto Role is disabled. For `human`, `bot`, `pending`, or `verified`, omitting the role mention saves an empty value and clears that setting. Do not treat the exempt-channel list as a substitute for an exempt role: the join handler checks member roles, not an event channel.

## Related pages

* [Self-service panels](/docs/en/server/roles/self-assignable.md)
* [Reaction Roles](/docs/en/server/roles/reaction-roles.md)
* [Headless permissions](/docs/en/permissions.md)


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