---
url: /commands/actions/change-roles.md
description: >-
  Действие «Изменение ролей» — выдача и снятие ролей бота вызвавшему или
  упомянутому участнику, в том числе по кнопке.
---

# Изменение ролей

<p class="lead">Действие выдает или снимает <b>роли бота</b> — тому, кто вызвал команду или нажал кнопку, либо участнику, которого упомянули.</p>

::: info Что такое роли бота
Роли бота — это роли, которые вы создаете в разделе **«Роли бота»**: у них есть название, цвет, эмодзи и приоритет. Их используют в правах команд, наградах за уровни и иммунитете к автомодерации. Если включить у роли «Тег участника», бот покажет ее название рядом с именем участника в чате.
:::

## Настройки { #settings }

| Поле | Описание |
|---|---|
| **Выдать** | Роли, которые нужно добавить |
| **Снять** | Роли, которые нужно убрать |
| **Кому** | **Вызвавшему** — тому, кто написал команду или нажал кнопку. **Упомянутому** — участнику из аргументов команды: на чье сообщение ответили или кого упомянули |

Как бот находит упомянутого участника — см. [Аргументы команды](../arguments#target).

## Пример: роль по кнопке { #button }

Сообщение с кнопкой «Хочу в турнир», которая выдает роль «Участник турнира».

**Действие 1 — «Анонс»** (по умолчанию), тип **Отправка сообщения**:

```template
# Турнир в субботу
Нажми кнопку, чтобы получить роль участника и доступ к топику турнира.
{% do button('SUCCESS', 'join', 'Хочу в турнир', '🏆', '3c8d7f2e-9a41-4b6e-8f0d-2e5b7c1a9d44') %}
```

**Действие 2 — «Выдать роль»**, тип **Изменение ролей**: выдать «Участник турнира», кому — вызвавшему. UUID этого действия подставлен в кнопку выше.

<TgPreview :buttons="[['🏆 Хочу в турнир|success']]">

# Турнир в субботу

Нажми кнопку, чтобы получить роль участника и доступ к топику турнира.

</TgPreview>

После нажатия бот выдаст роль тому, кто нажал кнопку.

## Роли из шаблона { #template }

Если набор ролей зависит от условий, используйте методы участника в шаблоне действий типа «Отправка сообщения» или «Выполнение кода»:

```template
{% if member.rank.level >= 20 %}
  {% do member.addRole('r_veteran') %}
  Ты получил роль «Ветеран»!
{% endif %}
```

| Метод | Что делает |
|---|---|
| `member.addRole(роль)` | Выдать роль |
| `member.removeRole(роль)` | Снять роль |
| `member.addRoles([роль, роль])`, `member.removeRoles([…])` | Несколько ролей сразу |
| `member.modifyRoles(выдать, снять)` | Выдать и снять одним вызовом |
| `member.addTempRole(роль, срок)` | Выдать на время: срок в миллисекундах или дата, не меньше 15 секунд |
| `member.hasRole(роль)` | Проверить, есть ли роль |

Роль указывается ее ID (виден в разделе **«Роли бота»**) или объектом роли — например, `chat.getRole('r_veteran')`.

## Ограничения { #limits }

* Бот учитывает иерархию ролей относительно того, кто вызвал команду: через команду нельзя выдать роль выше своей. Так хелпер не выдаст себе роль администратора.
* За одно выполнение — не больше 10 изменений ролей.
* Роли бота работают только внутри бота: они не меняют права участника в Telegram, но дают доступ к командам, иммунитет к фильтрам и множители опыта.