> 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/moderacion/moderation.md).

# Moderation Plugin

El plugin de Moderación proporciona un sistema completo de gestión de tu servidor con herramientas automáticas y manuales para mantener un ambiente seguro y ordenado.

***

## 📑 Contenido

* [Características Principales](#caracteristicas-principales)
* [Comandos de Moderación](#comandos-de-moderacion)
* [Sistema de Advertencias](#sistema-de-advertencias)
* [AutoMod](#automod)
* [Acciones Automáticas](#acciones-automaticas)
* [Configuración](#configuracion)
* [Casos de Uso](#casos-de-uso)
* [Mejores Prácticas](#mejores-practicas)
* [Solución de Problemas](#solucion-de-problemas)

***

## 🎯 Características Principales

### Plan Free

* ✅ `/kick` - Expulsar usuarios del servidor
* ✅ `/ban` - Banear usuarios permanentemente
* ✅ `/timeout` - Aplicar tiempo fuera temporal (hasta 28 días)
* ✅ `/untimeout` - Remover tiempo fuera activo
* ✅ `/unban` - Desbanear usuarios

### Plan Premium 💎

* ✅ **Todo lo del Plan Free**, más:
* ✅ **AutoMod** - Filtros automáticos de contenido
* ✅ **Sistema de Advertencias** - Seguimiento de infracciones
* ✅ **Acciones Automáticas** - Kick/Ban/Mute al alcanzar límite de advertencias
* ✅ **Ban Temporal** - Desban programado automático
* ✅ **Logs de Moderación** - Canal dedicado para auditoría

***

## ⚡ Comandos de Moderación

### `/kick usuario [razón] [schedule] [role]`

Expulsa a un usuario del servidor (puede volver a unirse).

**Parámetros:**

* `usuario` (requerido): Usuario a expulsar
* `razón` (opcional): Motivo de la expulsión
* `schedule` (opcional, 💎 Premium): Programar kick para fecha/hora específica (formato ISO date/time)
* `role` (opcional, 💎 Premium): Expulsar a todos los miembros con un rol específico

**Permisos necesarios:** Expulsar Miembros

**Ejemplos:**

```
/kick @Usuario Spam en canales
/kick @Usuario Comportamiento inapropiado schedule:2025-02-01T15:00:00
/kick role:@Spammers Limpieza masiva de spammers
```

***

### `/ban usuario [razón] [días] [duración]`

Banea a un usuario del servidor.

**Parámetros:**

* `usuario` (requerido): Usuario a banear
* `razón` (opcional): Motivo del ban
* `días` (opcional): Días de mensajes a eliminar
  * Free: 0-1 día
  * Premium: 0-7 días
* `duración` (opcional, 💎 Premium): Días de ban temporal
  * Si se especifica, el usuario será desbaneado automáticamente
  * Si no se especifica, el ban es permanente

**Permisos necesarios:** Banear Miembros

**Ejemplos:**

```
/ban @Usuario Spam grave
/ban @Usuario Comportamiento tóxico días:2 duración:7
```

***

### `/timeout usuario duración [razón]`

Aplica un tiempo fuera temporal a un usuario (no puede enviar mensajes ni unirse a canales de voz).

**Parámetros:**

* `usuario` (requerido): Usuario a silenciar
* `duración` (requerido): Minutos de timeout (1-40320 = 28 días)
* `razón` (opcional): Motivo del timeout

**Permisos necesarios:** Moderar Miembros

**Ejemplos:**

```
/timeout @Usuario 60 Discusión acalorada
/timeout @Usuario 1440 Spam (24 horas)
```

***

### `/untimeout usuario [razón]`

Remueve el timeout activo de un usuario.

**Parámetros:**

* `usuario` (requerido): Usuario a liberar
* `razón` (opcional): Motivo de la remoción

**Permisos necesarios:** Moderar Miembros

**Ejemplo:**

```
/untimeout @Usuario Disculpas aceptadas
```

***

### `/unban usuario [razón]`

Desbanea a un usuario previamente baneado.

**Parámetros:**

* `usuario` (requerido): ID del usuario a desbanear
* `razón` (opcional): Motivo del desban

**Permisos necesarios:** Banear Miembros

**Ejemplo:**

```
/unban 123456789012345678 Apelación aceptada
```

***

## ⚠️ Sistema de Advertencias (💎 Premium)

### `/warn usuario razón`

Añade una advertencia oficial al registro del usuario.

**Parámetros:**

* `usuario` (requerido): Usuario a advertir
* `razón` (requerido): Motivo de la advertencia

**Permisos necesarios:** Moderar Miembros

**Ejemplo:**

```
/warn @Usuario Lenguaje inapropiado
```

**¿Qué sucede?**

1. Se añade la advertencia al registro del usuario
2. El usuario recibe un mensaje directo informándole
3. Si alcanza el límite de advertencias, se aplica la acción automática configurada
4. El evento se registra en el canal de logs (si está configurado)

***

### `/warnings usuario`

Muestra el historial de advertencias de un usuario.

**Parámetros:**

* `usuario` (requerido): Usuario a consultar

**Permisos necesarios:** Moderar Miembros

**Ejemplo:**

```
/warnings @Usuario
```

**Información mostrada:**

* Número total de advertencias
* Límite máximo configurado
* Detalles de cada advertencia:
  * Fecha
  * Moderador que la aplicó
  * Razón

***

## 🤖 AutoMod (💎 Premium)

El sistema AutoMod filtra automáticamente contenido no deseado y aplica advertencias.

### Filtros Disponibles

#### 🚫 Spam

Detecta cuando un usuario envía demasiados mensajes en poco tiempo.

**Configuración:**

* Ventana de tiempo (predeterminado: 7 segundos)
* Máximo de mensajes permitidos (predeterminado: 5 mensajes)

**Acción:** Elimina el mensaje y aplica advertencia

***

#### 🔤 Mayúsculas Excesivas (CAPS)

Detecta mensajes con más del 70% en mayúsculas (mínimo 10 caracteres).

**Acción:** Elimina el mensaje y aplica advertencia

***

#### 🔗 Links

Bloquea todos los links externos (URLs con http\:// o https\://).

**Configuración:** Activar/Desactivar

**Acción:** Elimina el mensaje y aplica advertencia

***

#### 📬 Invitaciones de Discord

Bloquea invitaciones a otros servidores de Discord.

**Configuración:** Activar/Desactivar

**Acción:** Elimina el mensaje y aplica advertencia

***

#### 🤬 Palabras Prohibidas

Filtra palabras o frases específicas que definas.

**Configuración:**

1. Activar filtro de palabras
2. Añadir lista de palabras prohibidas en el dashboard

**Acción:** Elimina el mensaje y aplica advertencia

***

### Modo de Apilamiento de Advertencias

**Modo Normal** (predeterminado):

* Una advertencia por mensaje, sin importar cuántas reglas se violaron

**Modo Apilado** (stackWarnings):

* Una advertencia por cada regla violada en un mismo mensaje
* Ejemplo: Un mensaje con SPAM + CAPS + LINK = 3 advertencias

**Configuración:** Activar en el dashboard

***

## ⚙️ Acciones Automáticas (💎 Premium)

Cuando un usuario alcanza el límite de advertencias, el bot aplica automáticamente la acción configurada.

### Acciones Disponibles

#### 🚪 Kick (Expulsión)

Expulsa al usuario del servidor (puede volver a entrar).

**Configuración adicional:**

* Mensaje de DM personalizado (opcional)

***

#### 🔨 Ban (Baneo)

Banea al usuario del servidor.

**Configuración adicional:**

* Duración del ban (días):
  * Si se especifica: Ban temporal con desban automático
  * Si no se especifica: Ban permanente
* Días de mensajes a eliminar (0-7)

***

#### 🔇 Mute (Silencio Temporal)

Aplica timeout al usuario.

**Configuración adicional:**

* Duración del mute en minutos (predeterminado: 24 horas)

***

#### ❌ Ninguna

No aplica ninguna acción automática (solo mantiene el registro).

***

### Reinicio del Contador

Después de aplicar una acción automática, el contador de advertencias visibles se reinicia automáticamente. El historial completo se mantiene para auditoría.

***

## 🔧 Configuración

Toda la configuración se realiza desde el **Dashboard Web** en <https://gubo.com.ar>

### Configuración Básica

1. **Habilitar Plugin**: Activa el sistema de moderación
2. **Límite de Advertencias**: Número de advertencias antes de acción automática (predeterminado: 3)
3. **Acción Automática**: Qué hacer al alcanzar el límite
4. **Canal de Logs**: Canal donde se registrarán las acciones (💎 Premium)

### Configuración de AutoMod (💎 Premium)

1. **Activar AutoMod**: Habilita el filtrado automático
2. **Seleccionar Filtros**: Activa los filtros que desees usar
3. **Configurar Palabras Prohibidas**: Si usas el filtro de palabras
4. **Modo de Apilamiento**: Activar si deseas múltiples advertencias por mensaje

### Configuración de Acciones Automáticas

1. **Tipo de Acción**: Kick, Ban, Mute o Ninguna
2. **Duración de Ban** (si aplica): Días de ban temporal
3. **Duración de Mute** (si aplica): Minutos de timeout
4. **Mensaje de DM** (opcional): Mensaje personalizado al usuario

***

## 💡 Casos de Uso

### 1. Servidor de Comunidad General

**Configuración recomendada:**

* Límite de advertencias: 3
* AutoMod: CAPS + Links + Palabras prohibidas
* Acción automática: Timeout de 1 hora
* Stack warnings: No

**Objetivo:** Mantener conversaciones civilizadas sin ser demasiado estricto

***

### 2. Servidor de Gaming Competitivo

**Configuración recomendada:**

* Límite de advertencias: 5
* AutoMod: SPAM + CAPS + Invites
* Acción automática: Kick
* Stack warnings: Sí

**Objetivo:** Ambiente dinámico pero sin tolerancia a spam o raids

***

### 3. Servidor Educativo/Profesional

**Configuración recomendada:**

* Límite de advertencias: 2
* AutoMod: Todos los filtros activos
* Acción automática: Ban temporal de 7 días
* Stack warnings: Sí

**Objetivo:** Ambiente estrictamente profesional

***

### 4. Servidor de Comunidad Abierta

**Configuración recomendada:**

* Límite de advertencias: 5
* AutoMod: Solo SPAM + Invites
* Acción automática: Mute de 24 horas
* Stack warnings: No

**Objetivo:** Libertad de expresión con protección contra raids

***

## ✅ Mejores Prácticas

### Para Moderadores

1. **Documenta las razones**
   * Siempre incluye una razón clara en los comandos
   * Facilita la auditoría posterior
   * Ayuda a otros moderadores a entender el contexto
2. **Comunica las reglas**
   * Asegúrate de que los usuarios conozcan las reglas
   * Considera advertencias verbales antes de usar comandos
   * Sé consistente en la aplicación de reglas
3. **Revisa el historial**
   * Usa `/warnings` antes de aplicar sanciones graves
   * Considera el contexto y el comportamiento histórico
   * Sé justo y equitativo
4. **Usa la herramienta correcta**
   * Timeout: Para conflictos temporales o cooling-down
   * Kick: Para infracciones moderadas (pueden volver)
   * Ban: Para infracciones graves o recurrentes

### Para Administradores

1. **Configura el canal de logs**
   * Permite auditoría y transparencia
   * Restringe el acceso solo a moderadores/admins
   * Revísalo periódicamente
2. **Ajusta los límites**
   * Empieza con valores conservadores
   * Ajusta según el comportamiento de tu comunidad
   * Monitorea los falsos positivos
3. **Personaliza AutoMod**
   * No todos los filtros son necesarios para todos los servidores
   * Ajusta la lista de palabras prohibidas a tu contexto
   * Considera el idioma y cultura de tu comunidad
4. **Comunica las políticas**
   * Publica las reglas claramente
   * Explica el sistema de advertencias
   * Informa sobre las consecuencias

***

## 🛠️ Solución de Problemas

### ❌ Los comandos no funcionan

**Posibles causas:**

1. **Plugin deshabilitado**
   * ✅ Verifica que el plugin esté activado en el Dashboard
   * ✅ Asegúrate de haber guardado los cambios
2. **Permisos insuficientes**
   * ✅ El bot necesita los permisos de moderación correspondientes
   * ✅ Tu rol de usuario debe tener los permisos necesarios para ejecutar el comando
3. **Jerarquía de roles**
   * ✅ No puedes moderar a usuarios con roles iguales o superiores al tuyo
   * ✅ El bot no puede moderar usuarios con roles superiores al suyo
   * ✅ Verifica que el rol del bot esté por encima de los roles a moderar

***

### ❌ AutoMod no funciona

**Posibles causas:**

1. **Plan no Premium**
   * ✅ AutoMod es una característica exclusiva del plan Premium 💎
   * ✅ Verifica tu plan actual en el Dashboard
2. **Filtros desactivados**
   * ✅ Asegúrate de que los filtros estén activados en la configuración del Dashboard
   * ✅ Revisa que hayas guardado los cambios
3. **Falsos positivos**
   * ✅ Revisa la configuración de cada filtro en el Dashboard
   * ✅ Ajusta los umbrales si es necesario (por ejemplo, número de mensajes para spam)

* ✅ Considera exentar ciertos canales donde los filtros no sean necesarios

***

### ❌ Advertencias no se aplican

**Posibles causas:**

1. **Plan no Premium**
   * ✅ El sistema de advertencias es una característica Premium 💎
   * ✅ Verifica tu plan actual en el Dashboard
2. **Permisos insuficientes**
   * ✅ El bot necesita permisos para enviar mensajes en los canales
   * ✅ El bot necesita permisos para aplicar la acción automática que configuraste
   * ✅ Verifica los permisos del rol del bot en la configuración del servidor

***

### ❌ Canal de logs no recibe mensajes

**Soluciones:**

1. **Verificar configuración**
   * ✅ Confirma que el canal de logs esté seleccionado correctamente en el Dashboard
   * ✅ Verifica que el canal no haya sido eliminado
2. **Permisos del bot**

* ✅ El bot necesita permiso de "Ver Canal" en el canal de logs
  * ✅ El bot necesita permiso de "Enviar Mensajes" en el canal de logs
  * ✅ Revisa los permisos específicos del canal en la configuración del servidor

***

### ❌ Ban temporal no desbanea automáticamente

**Soluciones:**

1. **Verificar duración configurada**
   * ✅ Asegúrate de haber especificado la duración (en días) en el comando `/ban`
   * ✅ Ejemplo correcto: `/ban @Usuario Razón días:2 duración:7`
2. **El sistema revisa bans periódicamente**
   * ℹ️ El bot revisa los bans programados cada 10 minutos aproximadamente
   * ✅ El desban ocurrirá automáticamente en la siguiente revisión después del tiempo especificado

* ✅ Ten paciencia, el desban puede tardar hasta 10 minutos después de cumplirse el tiempo

***

## 📊 Comparativa Plan Free vs Premium

| Característica                                 | Free | Premium 💎 |
| ---------------------------------------------- | ---- | ---------- |
| Comandos básicos de moderación                 | ✅    | ✅          |
| `/kick`, `/ban`, `/timeout`                    | ✅    | ✅          |
| `/unban`, `/untimeout`                         | ✅    | ✅          |
| Ban temporal con desban automático             | ❌    | ✅          |
| Sistema de advertencias (`/warn`, `/warnings`) | ❌    | ✅          |
| **AutoMod**                                    | ❌    | ✅          |
| Filtro de spam                                 | ❌    | ✅          |
| Filtro de CAPS                                 | ❌    | ✅          |
| Filtro de links                                | ❌    | ✅          |
| Filtro de invites                              | ❌    | ✅          |
| Filtro de palabras prohibidas                  | ❌    | ✅          |
| **Acciones automáticas**                       | ❌    | ✅          |
| Kick automático                                | ❌    | ✅          |
| Ban automático                                 | ❌    | ✅          |
| Mute automático                                | ❌    | ✅          |
| **Canal de logs**                              | ❌    | ✅          |
| Stack de advertencias                          | ❌    | ✅          |

***

## 📞 Soporte

Si tienes problemas con el plugin de Moderación:

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

***