> For the complete documentation index, see [llms.txt](https://docs.rainmad.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rainmad.com/resources/watch-admin-menu/permissions/discord-roles.md).

# Discord roles

Give staff their group by Discord role: everyone holding a mapped role gets that group in game and on the web panel. Take the role away and the group goes with it.

## Pick a bot

rm\_watch reads roles with a Discord bot. Use one of the two:

{% tabs %}
{% tab title="Hosted bot (easiest)" %}
The fivemad Watch bot that also runs the [Discord commands](https://docs.rainmad.com/resources/watch-admin-menu/web-panel-and-discord/the-discord-bot). Nothing goes in `server.cfg`.

1. Link your Discord server to rm\_watch on the panel's **Settings, Discord** page (see [The Discord bot](https://docs.rainmad.com/resources/watch-admin-menu/web-panel-and-discord/the-discord-bot#setup)).
2. Map roles as below.

The hosted bot is only used when you have no token of your own.
{% endtab %}

{% tab title="Your own bot" %}

1. Create a bot in the [Discord developer portal](https://discord.com/developers/applications) and invite it to your Discord server. It needs no permissions, only to be a member.
2. Put its token in `server.cfg`:

```cfg
set rm_watch_discord_token "your-bot-token"
```

3. Put your Discord server id in `cfg.lua`:

```lua
cfg.admin.discord = {
    guild = '1234567890',
    roles = { owner = {}, admin = {}, moderator = {} },
}
```

{% endtab %}
{% endtabs %}

## Map roles to groups

Any group can be mapped, custom ones included. Two places do it:

| Where     | How                                                           |
| --------- | ------------------------------------------------------------- |
| In game   | **Staff** tab, **Discord roles**.                             |
| Web panel | **Staff and roles**, **Discord roles** tab.                   |
| `cfg.lua` | `cfg.admin.discord.roles`, for the three built-in roles only. |

```lua
cfg.admin.discord.roles = {
    owner     = { '111111111111111111' },
    admin     = { '222222222222222222' },
    moderator = { '333333333333333333', '444444444444444444' },
}
```

* Someone holding several mapped roles gets the **highest** ranked group.
* A role id in both `cfg.lua` and the menu uses the `cfg.lua` mapping.
* You can only map a group you could give to one person yourself.

## When roles are read

When a player joins, every 10 minutes while they are online, and at once when a mapping changes.

## Pushing roles back to Discord

By default the sync only goes from Discord to the game. To also give the Discord role when someone gets a group in game or on the panel:

```lua
cfg.roles = { pushToDiscord = true }
```

The new group's first mapped role is given and the old group's roles are taken away. The bot then needs **Manage Roles**, and its own role must sit above the roles it hands out.
