> For the complete documentation index, see [llms.txt](https://gubo.gitbook.io/gubo-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gubo.gitbook.io/gubo-docs/engagement/reaction-roles.md).

# Reaction Roles Plugin

El plugin de Reaction Roles permite a los usuarios obtener roles simplemente reaccionando con emojis a mensajes específicos.

***

## 📑 Contenido

* [Características Principales](#caracteristicas-principales)
* [Cómo Funciona](#como-funciona)
* [Uso para Usuarios](#uso-para-usuarios)
* [Configuración](#configuracion)
* [Modos de Selección](#modos-de-seleccion)
* [Rate Limiting](#rate-limiting)
* [Casos de Uso](#casos-de-uso)
* [Mejores Prácticas](#mejores-practicas)
* [Solución de Problemas](#solucion-de-problemas)

***

## 🎯 Características Principales

### Plan Free

* ✅ **1 panel** de reaction roles
* ✅ **1 emoji-rol** por panel
* ✅ **Asignación automática** al reaccionar
* ✅ **Rate limiting básico** (protección anti-spam)

### Plan Premium 💎

* ✅ **Todo lo del Plan Free**, más:
* ✅ **Múltiples paneles** ilimitados
* ✅ **Múltiples emojis-roles** por panel
* ✅ **Modo multi-select** (varios roles a la vez)
* ✅ **Modo single-select** (solo un rol del panel)
* ✅ **removeOnUnreact** - Quitar rol al remover reacción
* ✅ **Rate limiting mejorado** (más acciones permitidas)

***

## ⚙️ Cómo Funciona

### Concepto Básico

1. Un administrador crea un **mensaje** con instrucciones
2. Configura qué **emoji** da qué **rol**
3. Los usuarios **reaccionan** al mensaje con el emoji
4. El bot **asigna el rol** automáticamente

**Ejemplo:**

```
Mensaje: "Reacciona para elegir tu color favorito"

🔴 = Rol Rojo
🔵 = Rol Azul
🟢 = Rol Verde

Usuario reacciona con 🔴 → Recibe el rol Rojo
```

***

## 👥 Uso para Usuarios

### Obtener un Rol

1. **Encuentra el mensaje de reaction roles**
   * Generalmente en un canal #roles o #selección-de-roles
2. **Lee las instrucciones**
   * Cada panel explica qué rol da cada emoji
3. **Reacciona con el emoji**
   * Haz clic en el emoji correspondiente
   * El bot asigna el rol automáticamente (1-3 segundos)
4. **Verifica tu rol**
   * Revisa tu lista de roles
   * El nuevo rol debería aparecer

### Quitar un Rol

**Si `removeOnUnreact` está activo:**

* Simplemente **remueve tu reacción**
* Haz clic de nuevo en el emoji
* El bot quita el rol automáticamente

**Si `removeOnUnreact` está desactivado:**

* Contacta a un moderador para que te quite el rol manualmente

***

## ⚙️ Configuración

### En el Dashboard

Accede a <https://gubo.com.ar> > Tu Servidor > Reaction Roles

#### Paso 1: Crear el Mensaje

1. En Discord, envía un mensaje en el canal deseado
2. Copia el **ID del mensaje** (clic derecho > Copiar ID del Mensaje)
3. Copia el **ID del canal** (clic derecho en el canal > Copiar ID)

#### Paso 2: Crear el Panel

En el dashboard:

1. Haz clic en "Nuevo Panel"
2. Completa:

| Campo                 | Descripción                        | Requerido |
| --------------------- | ---------------------------------- | --------- |
| **ID del Mensaje**    | ID del mensaje de Discord          | ✅         |
| **ID del Canal**      | ID del canal donde está el mensaje | ✅         |
| **Modo**              | Multi-select o Single-select       | ✅         |
| **Remove on Unreact** | Quitar rol al remover reacción     | ❌         |

#### Paso 3: Añadir Emoji-Roles

Para cada rol que quieras asignar:

1. Haz clic en "Añadir Emoji-Rol"
2. Configura:

| Campo                 | Descripción                              | Ejemplo              |
| --------------------- | ---------------------------------------- | -------------------- |
| **Emoji**             | Emoji Unicode o ID de emoji del servidor | 🎮 o :custom\_emoji: |
| **ID del Rol**        | ID del rol a asignar                     | 123456789012345678   |
| **Remove on Unreact** | Específico para este emoji               | Opcional             |

#### Paso 4: Añadir Reacciones al Mensaje

1. Ve al mensaje en Discord
2. Reacciona con cada emoji configurado
3. Esto permite que los usuarios vean las opciones

***

## 🎲 Modos de Selección

### Multi-Select (💎 Premium)

Los usuarios pueden tener **varios roles** del mismo panel a la vez.

**Ejemplo:**

```
Panel: Juegos Favoritos

🎮 Gamer
🎯 FPS
🏎️ Racing
⚔️ RPG

Un usuario puede tener todos estos roles simultáneamente.
```

**Cuándo usar:**

* Preferencias múltiples
* Intereses/hobbies
* Plataformas donde juegan
* Notificaciones (varios temas)

***

### Single-Select (💎 Premium)

Los usuarios solo pueden tener **un rol** del panel a la vez.

**Ejemplo:**

```
Panel: Tu Región

🌎 América
🌍 Europa
🌏 Asia
🌐 Oceanía

Si el usuario tiene Europa y reacciona a Asia,
automáticamente pierde Europa y obtiene Asia.
```

**Cuándo usar:**

* Opciones excluyentes
* Rango/nivel
* Equipos competitivos
* Elección única

***

## ⏱️ Rate Limiting

El sistema incluye protección anti-spam para evitar abuso.

### Límites

**Plan Free:**

* Máximo **3 acciones** (añadir/quitar roles) por minuto
* Si excedes el límite: espera 60 segundos

**Plan Premium:**

* Máximo **20 acciones** por minuto
* Más flexible para usuarios legítimos

### Notificaciones

**Si excedes el límite:**

* Recibes un DM indicando cuánto esperar
* El dueño del servidor también puede recibir notificación (configurable)
* Las reacciones no procesan hasta que pase el tiempo

**Configuración de notificaciones:**

* `dmUserOnRateLimit`: Notificar al usuario
* `dmOwnerOnRateLimit`: Notificar al dueño

***

## 💡 Casos de Uso

### 1. Roles de Notificaciones

**Configuración:**

* Modo: Multi-select
* Remove on Unreact: ✅ Sí

**Emojis:**

* 📢 Anuncios
* 🎉 Eventos
* 🎮 Gaming
* 🎨 Arte

**Beneficio:** Los usuarios eligen qué notificaciones recibir

***

### 2. Selección de Equipo

**Configuración:**

* Modo: Single-select
* Remove on Unreact: ❌ No (permanente)

**Emojis:**

* 🔴 Equipo Rojo
* 🔵 Equipo Azul

**Beneficio:** Los usuarios solo pueden estar en un equipo

***

### 3. Pronombres

**Configuración:**

* Modo: Multi-select
* Remove on Unreact: ✅ Sí

**Emojis:**

* 👨 Él/He/Him
* 👩 Ella/She/Her
* 🧑 Elle/They/Them

**Beneficio:** Respeto a la identidad de cada usuario

***

### 4. Intereses/Hobbies

**Configuración:**

* Modo: Multi-select
* Remove on Unreact: ✅ Sí

**Emojis:**

* 🎵 Música
* 📚 Lectura
* 🎨 Arte
* 💻 Programación
* 🎮 Gaming

**Beneficio:** Los usuarios encuentran personas con intereses similares

***

### 5. Nivel/Rango

**Configuración:**

* Modo: Single-select
* Remove on Unreact: ❌ No

**Emojis:**

* 🥉 Bronce
* 🥈 Plata
* 🥇 Oro
* 💎 Diamante

**Beneficio:** Jerarquía clara, solo un rango a la vez

***

## ✅ Mejores Prácticas

### Para Administradores

1. **Mensajes claros**
   * Explica qué hace cada emoji
   * Usa formato markdown para destacar
   * Añade instrucciones claras
2. **Emojis apropiados**
   * Usa emojis que representen claramente el rol
   * Evita emojis similares que confundan
   * Considera usar emojis personalizados del servidor
3. **Organización**
   * Crea paneles separados por temática
   * No mezcles muchos tipos de roles en un panel
   * Un panel para notificaciones, otro para juegos, etc.
4. **Permisos del bot**
   * El bot necesita "Gestionar Roles"
   * El rol del bot debe estar por encima de los roles a asignar
   * Verifica la jerarquía
5. **Testing**
   * Prueba cada emoji antes de publicar
   * Verifica que todos funcionen correctamente
   * Pide a otros moderadores que prueben

### Para Usuarios

1. **Lee las instrucciones**
   * Cada panel puede funcionar diferente
   * Verifica si es multi o single-select
2. **No hagas spam con reacciones**
   * El sistema de rate limiting te bloqueará temporalmente
   * Espera unos segundos entre reacciones
3. **Verifica tus roles**
   * Confirma que recibiste el rol correcto
   * Si no funciona, reporta a un moderador

***

## 🛠️ Solución de Problemas

### ❌ No recibo el rol al reaccionar

**Soluciones:**

1. **Espera unos segundos**
   * El bot puede tardar 1-3 segundos en procesar tu reacción
2. **Permisos del bot**
   * ✅ El bot necesita el permiso "Gestionar Roles"
   * ✅ El rol del bot debe estar por encima del rol a asignar en la jerarquía
   * ✅ Contacta a un administrador si esto no está configurado
3. **Configuración incorrecta**
   * ✅ Verifica que el emoji esté configurado correctamente en el Dashboard
   * ✅ Confirma que el ID del rol sea correcto
   * ✅ Contacta a un administrador para revisar la configuración
4. **Rate limit activo**
   * ✅ Si reaccionaste muchas veces en poco tiempo, el sistema te bloquea temporalmente
   * ✅ Espera 60 segundos e intenta de nuevo

***

### ❌ El rol no se quita al remover reacción

**Soluciones:**

1. **Función desactivada**
   * ℹ️ La opción "Remove on Unreact" puede estar desactivada en este panel
   * ✅ Contacta a un moderador para que te quite el rol manualmente
2. **Permisos insuficientes**
   * ✅ El bot necesita los mismos permisos que para asignar roles
   * ✅ Contacta a un administrador para revisar los permisos

***

### ❌ No puedo añadir más emojis (Plan Free)

**Soluciones:**

1. **Límite del Plan Free alcanzado**
   * ℹ️ El Plan Free permite solo 1 panel con 1 emoji-rol
   * ✅ Para múltiples opciones, contacta al dueño del servidor sobre actualizar a Premium 💎

***

### ❌ El panel no funciona

**Soluciones:**

1. **Plugin deshabilitado**
   * ✅ Verifica que el plugin esté activo en el Dashboard
   * ✅ Asegúrate de haber guardado los cambios
2. **IDs incorrectos**
   * ✅ Confirma que el ID del mensaje sea correcto
   * ✅ Confirma que el ID del canal sea correcto
   * ✅ Puedes copiar los IDs haciendo clic derecho (requiere Modo Desarrollador activado)
3. **Mensaje eliminado**
   * ✅ Si el mensaje original fue eliminado, el panel dejará de funcionar
   * ✅ Crea un nuevo mensaje y actualiza la configuración en el Dashboard

***

## 📊 Comparativa Plan Free vs Premium

| Característica               | Free  | Premium 💎 |
| ---------------------------- | ----- | ---------- |
| Paneles                      | 1     | Ilimitados |
| Emojis por panel             | 1     | Ilimitados |
| Multi-select                 | ❌     | ✅          |
| Single-select                | ❌     | ✅          |
| Remove on unreact            | ❌     | ✅          |
| Rate limiting                | 3/min | 20/min     |
| Notificaciones de rate limit | ❌     | ✅          |

***

## 📞 Soporte

Si tienes problemas con el plugin de Reaction Roles:

1. ✅ Revisa esta guía completa
2. ✅ Consulta la sección de [Solución de Problemas](#solucion-de-problemas)
3. ✅ Verifica la configuración en el Dashboard
4. ✅ Confirma que el bot tenga los permisos necesarios
5. ✅ Contacta al soporte técnico de GUBO

***

**Última actualización:** Enero 2026

**Versión de la guía:** 1.0.0

***