HELPER Discord Bot
← К списку Wiki
REACTION ROLES // EMOJI ACCESS // WEB SYNC

HELPER REACTION ROLES РОЛИ ЗА РЕАКЦИИ /ROLEPANEL / EMOJI → ROLE / MESSAGE_ID SYNC / ADMIN MENU

Reaction Roles превращает выдачу ролей в понятную Discord-плашку: пользователь ставит emoji под сообщением и получает нужную роль. Администратор настраивает панели через сайт или через кнопку ⚙️ Управление, а HELPER обновляет уже опубликованное сообщение по message_id, не создавая дублей.

Показать картинки Путь роли Настройка сайта
25панелей максимум
20emoji → role на панель
5ssite sync loop
v13panel-level remove mode
Panelплашка хранит message_id
Reactionon_raw_reaction_add выдаёт роль
Removeallow_remove работает на всю панель
Webdeploy_requested обновляет Discord
Safetyrole position + module state
// MODULE_PURPOSE

Что делает Reaction Roles

Модуль создаёт одну или несколько ролевых панелей. У каждой панели есть канал, сообщение, красивый embed, список связок emoji → role, режим снятия ролей, админ-кнопка и статус открытия. Пользователь взаимодействует без slash-команд — просто нажимает реакцию.

01

Панель

Администратор выбирает канал, текст, баннер, цвет и список ролей.

02

Emoji

Каждая реакция привязана к конкретной Discord-роли.

03

Реакция

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

04

Sync

Сайт ставит deploy_requested, а cog редактирует старую плашку.

// VISUAL_GUIDE

Больше информации картинками

Полный путь: создание панели, добавление emoji → role, публичная плашка, реакция игрока, админ-меню, add-only режим, web-sync и закрытый disabled-state.

01 / setupСоздание плашки
🎭
slash command/rolepanel

Первая ролевая плашка

Если систем ещё нет, команда создаёт default panel в выбранном канале и сразу публикует embed.

/rolepanel channel:#получение-ролей
✅ Первая ролевая плашка создана
02 / public panelПубличная плашка
🎭
#rolesПолучение ролей

🎭 Получение ролей

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

📢Новости проекта.
🎁Розыгрыши и призы.
🚀Boosty и закрытые объявления.
⚙️ Управление
03 / player clickИгрок ставит реакцию

📢 → @Новости

on_raw_reaction_add находит систему по message_id и emoji, проверяет модуль, panel state, item state и выдаёт роль.

member.add_roles(role)
04 / admin menuDiscord admin-меню
⚙️
ephemeralУправление плашкой

⚙️ Управление Reaction Roles

Открывается только администраторам или ролям из admin_role_ids.

➕ Из списков
✍️ Вручную
✏️ Текст
🗑️ Удалить
🔴 Открыть/закрыть
🔐 Снятие
05 / emoji pickerВыбор emoji и роли
role selectemoji selectmax 25 options
Роль@Новости выбрана из Discord Select
ok
Emoji📢 из каталога или серверный emoji
select
Описание“получать новости проекта”
text
Saveплашка обновляется без дубля
deploy
06 / closed stateПлашка закрыта

🔴 Получение ролей закрыто

Панель может быть закрыта отдельно от всего модуля. Реакции остаются как легенда, но новые роли не выдаются.

closed_description
// DISCORD_COMMANDS

Команда Discord

В текущем модуле основная команда одна. Всё остальное вынесено в кнопки, select-меню и modal-окна, чтобы не плодить десятки slash-команд.

admin command/rolepanel
/rolepanel channel:#получение-ролей

Создаёт первую панель или открывает админ-меню первой существующей панели. Доступно администраторам сервера.

public interactionРеакции под плашкой
on_raw_reaction_add → add role on_raw_reaction_remove → remove role if allow_remove=true

Обычный пользователь не вводит команды: он нажимает emoji под сообщением.

admin button⚙️ Управление
RolePanelPublicView → open_admin_menu → RolePanelAdminView

Кнопка открывает private admin menu, если пользователь проходит can_manage_panel.

modal toolsModal / Select
AddReactionRoleItemModal DeleteReactionRoleItemModal EditRolePanelTextModal RoleEmojiPickerView

Настройка ролей и текста происходит без ручного редактирования JSON.

// REACTION_FLOW

Путь роли от emoji до доступа

1Panel

message_id

2Emoji

reaction

3Lookup

system/item

4Check

state/role

5Role

add/remove

6Access

Discord perms

A

Anti-duplicates

send_or_edit_panel редактирует старое сообщение по message_id и last_channel_id.

B

Hash sync

panel_hash сравнивает важные поля и не деплоит лишний раз.

C

Safe reaction

Если модуль или item выключен — реакция пользователя удаляется, а роль не выдаётся.

// PLAYER_FLOW

Что видит обычный участник

get roleПолучить роль

✅ Роль выдана

Игрок нажимает emoji. Discord сразу показывает новые каналы, если права сервера настроены на эту роль.

📢 → @Новости
remove roleСнять роль

Убрал реакцию

Если allow_remove=true, роль снимается. Если allow_remove=false, реакцию можно убрать, но роль остаётся.

allow_remove panel mode
closedЕсли плашка закрыта

🔴 Недоступно

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

panel closed
no commandsБез команд

Простая логика

Участнику не нужно знать /rolepanel. Он просто читает описание и выбирает нужные emoji.

click emoji only
// ADMIN_FLOW

Что делает администратор

01

Создаёт роли

@Новости, @Розыгрыши, @Клиенты, @Boosty или любые роли доступа.

02

Настраивает панель

Канал, embed, баннер, цвет, auto legend и show admin button.

03

Добавляет emoji

Через сайт, modal или RoleEmojiPickerView выбирает emoji → роль.

04

Проверяет права

Роль бота должна быть выше выдаваемых ролей и иметь Manage Roles.

Практический совет

Сначала создай роли и выставь роль бота выше них, потом создавай плашку. Тогда HELPER сразу сможет проверить role_is_assignable и добавить реакции.

// DASHBOARD_SETTINGS

Настройка на сайте

Сайт хранит панели в data/reaction_roles_settings.json. Когда владелец меняет настройки, сайт ставит deploy_requested, а cog каждые 5 секунд синхронизирует Discord.

system fieldsПоля панели
id / nameвнутренний ID и название панели.
enabledоткрыта или закрыта конкретная плашка.
channel_idканал публикации.
message_id / last_channel_idсвязка с Discord-сообщением для edit без дублей.
allow_removeможет ли пользователь снять роль сам.
admin_role_idsдополнительные роли управления панелью.
embed fieldsВизуал embed
authorверхняя подпись панели.
titleзаголовок embed.
descriptionосновной текст.
footerниз карточки + online/closed.
image_url / thumbnail_urlбаннер и миниатюра.
colorцвет embed-линии.
json previewreaction_roles_settings.json
data/reaction_roles_settings.json
{ "123456789": { "systems": [ { "id": "main_roles", "name": "Получение ролей", "enabled": true, "channel_id": "111", "message_id": "222", "allow_remove": true, "auto_legend": true, "items": [ {"emoji": "📢", "role_id": "333", "label": "Новости"}, {"emoji": "🎁", "role_id": "444", "label": "Розыгрыши"} ] } ], "deploy_requested": true } }
site syncsite_sync_loop

5 секунд

Loop читает все guild settings, проверяет module_states, сравнивает panel_hash и вызывает deploy_system.

deploy_requested → deploy_system → save message_id
// EMOJI_LIBRARY

Emoji, роли и описание

Хорошая ролевая плашка должна не просто показать emoji, а объяснить, какую роль получит участник и какой доступ она открывает.

common emojisГотовые emoji
commonserver emojimanual
📢 Новостиполучать анонсы проекта
role
🎁 Розыгрышиучастие в призах и событиях
role
🚀 Boostyобновления для подписчиков
role
🛠️ Обновленияchangelog и техработы
role
item fieldsПоля item
emojiUnicode или custom emoji вида <:name:id>.
role_idроль, которую выдаёт бот.
labelкрасивое название в легенде.
descriptionобъяснение, зачем нужна роль.
enabledможно временно отключить отдельную связку.
limitationsNitro / external emoji

Discord-ограничения

Модуль не обходит Nitro. Безопасный вариант: стандартные emoji или emoji текущего сервера, к которым бот имеет доступ.

<:name:id> должен быть доступен боту
legendAuto legend

auto_legend=true

HELPER автоматически добавляет в описание строки emoji — роль — описание. Если item выключен, он отображается как недоступный.

build_legend(system)
// REMOVE_MODE

Снятие ролей на уровне панели

В v13 снятие роли контролируется всей плашкой, а не отдельной emoji-связкой. Это убирает конфликт, когда у разных item внутри одной панели были разные правила.

allow_remove trueУведомления

allow_remove = true

Игрок поставил 📢 — получил @Новости. Убрал 📢 — роль снялась. Подходит для ping-уведомлений.

add role / remove role
allow_remove falseПостоянный доступ

allow_remove = false

Игрок поставил ✅ — получил @Доступ. Убрал ✅ — роль остаётся до ручного снятия staff.

add-only panel

Где это видно

В auto legend появляется подсказка “🔒 нельзя снять самому”, а в admin menu есть кнопка “Снятие ролей”.

// PERMISSIONS

Права бота и типовые ошибки

01

Manage Roles

Без этого права бот не сможет выдавать и снимать роли.

02

Role position

Роль HELPER должна быть выше всех ролей, которые он выдаёт.

03

Add Reactions

Чтобы сам бот добавил emoji под embed-плашку.

04

Read History

Нужно для корректной работы reaction events и редактирования старых сообщений.

role checkrole_is_assignable
role_not_foundроль удалена или ID неверный.
managed_roleроль интеграции нельзя выдать вручную.
role_too_highроль выше или равна роли бота.
missing_permissionsнет Manage Roles.
manager accessКто может управлять
administratorадминистратор сервера.
manage_guildправо управления сервером.
manage_rolesправо управления ролями.
admin_role_idsдополнительные роли, указанные в панели.
// SAFE_DISABLED

Если модуль выключен

Глобальный тумблер сайта меняет module_states.json. После этого cog пересинхронизирует опубликованные панели: embed становится красным, а реакции больше не выдают роли.

disabled panelЧто видит пользователь
🔌
safe stateРолевые панели отключены

🔌 РОЛЕВЫЕ ПАНЕЛИ ОТКЛЮЧЕНЫ

Модуль “Роли за реакции” выключен в панели управления сайта. Выдача ролей временно недоступна.

🔌 РОЛИ ЗА РЕАКЦИИ ОБЕСТОЧЕНЫ
state aliasesКлючи состояния
reaction_rolesосновной ключ.
reaction-rolesalias для старых сохранений.
role_panels / role-panelalias панели ролей.
roleslegacy alias, проверяется последним.
// DEVELOPER_MAP

Карта технической логики

filesФайлы и данные
SETTINGS_FILE

data/reaction_roles_settings.json — панели, items, embed, deploy.

MODULES_FILE

data/module_states.json — глобальное включение/выключение.

cog.py

site_sync_loop, deploy_system, reaction listeners и /rolepanel.

settings.py

normalize_system, normalize_items, panel_hash и safe migrations.

views.py / modals.py

public manage button, admin menu, role/emoji picker и modal-редактирование.

limitsГлавные лимиты
🎭
MAX_SYSTEMS25 панелей
😊
MAX_ITEMS20 emoji
🔁
SYNC5 секунд
⚠️
DEPLOY5 попыток
📋
SELECT25 options
🔐
ALLOWpanel level
sync logicWeb → Discord
deploy_requestedсайт или modal просит обновить панель.
panel_hashсравнение важных полей панели.
send_or_edit_paneledit старого сообщения или send нового.
sync_reactionsудаляет лишние реакции и добавляет актуальные.
save_full_guild_settingsсохраняет message_id и last_channel_id.
reaction logicon_raw_reaction
emoji_keyнормализация emoji.
find_system_and_itemпо message_id + emoji.
is_module_activeглобальное состояние модуля.
role_is_assignableправа и позиция роли.
add_roles/remove_rolesитоговое действие Discord.
// TROUBLESHOOTING

Ошибки и решения

Пользователь ставит реакцию, но роль не выдаётся

Проверьте, что модуль включён, панель enabled, item enabled, роль существует, а роль бота выше выдаваемой роли.

Плашка дублируется

Проверьте message_id и last_channel_id в settings. Если старое сообщение удалено или недоступно, бот создаст новое и сохранит новый ID.

Бот не может добавить custom emoji

У бота должен быть доступ к этому emoji. Внешние/Nitro emoji не обходятся.

Почему роль не снимается после удаления реакции?

На панели может быть allow_remove=false. Тогда пользователь может убрать реакцию, но роль остаётся до ручного снятия администратором.

Сайт сохранил, но Discord не обновился

Проверьте deploy_attempts, last_deploy_error и права бота в канале: View Channel, Send Messages, Embed Links, Add Reactions, Read Message History.

Кто может открыть ⚙️ Управление?

Администраторы, пользователи с Manage Guild / Manage Roles или роли, указанные в admin_role_ids конкретной панели.

// WIKI_NAVIGATION

Вернуться к списку Wiki

Ты дошёл до конца страницы Reaction Roles. Можно вернуться в общий центр документации, открыть Dashboard или подняться наверх к началу этой страницы.

← К списку Wiki Dashboard Наверх ↑