> 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/comunidad/welcome.md).

# Welcome Plugin

El plugin Welcome permite dar la bienvenida automáticamente a nuevos miembros cuando se unen a tu servidor de Discord. Ofrece múltiples opciones de personalización incluyendo mensajes en canales, mensajes directos, tarjetas personalizadas y roles automáticos.

***

## 📑 Contenido

* [Características Principales](#caracteristicas-principales)
* [Configuración](#configuracion)
* [Variables Dinámicas](#variables-dinamicas)
* [Ejemplos de Configuración](#ejemplos-de-configuracion)
* [Plantilla por Defecto](#plantilla-por-defecto)
* [Casos de Uso Comunes](#casos-de-uso-comunes)
* [Mejores Prácticas](#mejores-practicas)
* [Notas Técnicas](#notas-tecnicas)
* [Solución de Problemas](#solucion-de-problemas)

***

## 📑 Características Principales

### Plan Free

* ✅ Mensajes de texto básicos de bienvenida
* ✅ Variables dinámicas avanzadas
* ✅ Configuración de canal personalizado
* ✅ Creación automática de canal Welcome
* ✅ Imágenes de bienvenida
* ✅ Emojis personalizados y del servidor
* ✅ Referencias a canales

### Plan Premium 💎

* ✅ **Todo lo del Plan Free**, más:
* ✅ **Embeds personalizados** con colores configurables
* ✅ **Auto-roles** - Asignación automática de roles
* ✅ **Mensajes directos (DM)** personalizados
* ✅ **Tarjetas personalizadas** generadas dinámicamente
* ✅ **Ícono del servidor** en embeds o tarjetas
* ✅ Diseño visual premium

***

## ⚙️ Configuración

### Acceder a la Configuración

1. Ve al **Dashboard** en <https://gubo.com.ar>
2. Selecciona tu servidor
3. Ve a la sección **Plugins**
4. Haz clic en **Welcome Plugin**

### Opciones Disponibles

#### Configuración Básica

| Opción                   | Descripción                          | Plan         |
| ------------------------ | ------------------------------------ | ------------ |
| **Plugin Activado**      | Habilita o deshabilita el plugin     | Free/Premium |
| **Canal de Bienvenidas** | Canal donde se enviarán los mensajes | Free/Premium |
| **Mensaje**              | Texto personalizado de bienvenida    | Free/Premium |
| **Imagen de Fondo**      | URL de imagen para el mensaje        | Free/Premium |

#### Configuración Premium 💎

| Opción                    | Descripción                               | Requiere   |
| ------------------------- | ----------------------------------------- | ---------- |
| **Usar Embed**            | Formato elegante con color                | 💎 Premium |
| **Color del Embed**       | Color en formato hexadecimal (#00ff00)    | 💎 Premium |
| **Auto-Roles**            | Roles asignados automáticamente al unirse | 💎 Premium |
| **Mensaje Directo (DM)**  | Enviar DM privado al usuario              | 💎 Premium |
| **Mensaje de DM**         | Contenido del mensaje directo             | 💎 Premium |
| **Imagen de DM**          | URL de imagen para el DM                  | 💎 Premium |
| **Tarjeta Personalizada** | Generar imagen con avatar del usuario     | 💎 Premium |
| **Ícono del Servidor**    | Mostrar en embed o tarjeta                | 💎 Premium |

***

## 📑 Variables Dinámicas

Personaliza tus mensajes con estas variables que se reemplazan automáticamente:

### Variables Básicas

| Variable          | Descripción              | Ejemplo         |
| ----------------- | ------------------------ | --------------- |
| `{{user}}`        | Mención del usuario      | `@Usuario#1234` |
| `{{guild}}`       | Nombre del servidor      | `Mi Servidor`   |
| `{{memberCount}}` | Número total de miembros | `250`           |
| `{{memberIndex}}` | Número de miembro        | `#250`          |

### Variables de Usuario

| Variable             | Descripción                 | Ejemplo              |
| -------------------- | --------------------------- | -------------------- |
| `{{user.id}}`        | ID del usuario              | `123456789012345678` |
| `{{user.tag}}`       | Tag completo del usuario    | `Usuario#1234`       |
| `{{user.name}}`      | Nombre del usuario          | `Usuario`            |
| `{{user.createdAt}}` | Fecha de creación de cuenta | `Jan 15, 2020`       |
| `{{accountAge}}`     | Antigüedad de la cuenta     | `3 years ago`        |
| `{{isBot}}`          | Si es un bot                | `false`              |

### Variables de Roles

| Variable        | Descripción              | Ejemplo                |
| --------------- | ------------------------ | ---------------------- |
| `{{topRole}}`   | Rol más alto del usuario | `Miembro`              |
| `{{roleCount}}` | Cantidad de roles        | `3`                    |
| `{{roles}}`     | Lista de todos los roles | `Miembro, Activo, VIP` |

### Variables del Servidor

| Variable                       | Descripción                     | Ejemplo              |
| ------------------------------ | ------------------------------- | -------------------- |
| `{{guild.id}}`                 | ID del servidor                 | `987654321098765432` |
| `{{serverCreationDate}}`       | Fecha de creación del servidor  | `Mar 10, 2019`       |
| `{{boosts}}`                   | Número de boosts                | `15`                 |
| `{{premiumSubscriptionCount}}` | Suscriptores premium            | `15`                 |
| `{{joinedAt}}`                 | Fecha en que el usuario se unió | `Jan 31, 2025`       |

### Referencias Especiales

| Sintaxis                   | Descripción                                         | Ejemplo                          |
| -------------------------- | --------------------------------------------------- | -------------------------------- |
| `{#channelId}`             | Referencia a canal                                  | `<#123456789>`                   |
| `{channel:channelId}`      | Referencia a canal (alternativa)                    | `<#123456789>`                   |
| `{{channelRef:channelId}}` | Referencia a canal (formato usado por el dashboard) | `<#123456789>`                   |
| `{emoji:name}`             | Emoji del servidor o Unicode                        | `🔥` o emoji personalizado       |
| `{emoji:emojiId}`          | Emoji por ID                                        | Emoji personalizado del servidor |

### Ejemplo Completo

```
{emoji:star} ¡Bienvenido {{user}} a **{{guild}}**!

Tu ID de usuario es `{{user.id}}`, y tu tag completo es **{{user.tag}}**.
Tu cuenta, **{{user.name}}**, fue creada el **{{user.createdAt}}**, hace **{{accountAge}}**.

¡Ahora tenemos **{{memberCount}} miembros** en total (¡eres el miembro #**{{memberIndex}}**!

Tu rol más alto es **{{topRole}}**, y actualmente tienes **{{roleCount}} roles**: {{roles}}.

Te uniste a este servidor el **{{joinedAt}}**, que fue fundado el **{{serverCreationDate}}**,
y actualmente tiene **{{boosts}} boosts** ({{premiumSubscriptionCount}} suscriptores premium).

El ID del servidor es `{{guild.id}}`.
¿Eres un bot? **{{isBot}}**

¡Estamos muy contentos de tenerte aquí! {emoji:smile}

Revisa {#1234567890} para comenzar, y pasa por {channel:9876543210} para presentarte.

{emoji:fire} ¡Que comience la aventura!
```

***

## 📝 Ejemplos de Configuración

### 1️⃣ Configuración Básica (Free)

**Para:** Servidor simple que quiere dar la bienvenida a nuevos miembros

**Pasos en el Dashboard:**

1. Activa el plugin Welcome
2. Seleccionar canal de bienvenida
3. Escribe tu mensaje: `¡Bienvenido {{user}} a {{guild}}! Ahora somos {{memberCount}} miembros. 👋`

**Resultado:** Mensaje simple de texto en el canal #welcome

***

### 2️⃣ Configuración con Imagen (Free)

**Para:** Servidor que quiere una bienvenida visual

**Pasos en el Dashboard:**

1. Activa el plugin Welcome
2. Selecciona el canal: #bienvenida
3. Escribe tu mensaje: `🎉 ¡Bienvenido {{user}} a **{{guild}}**! Eres nuestro miembro #{{memberIndex}}.`
4. Añade la URL de tu imagen en "Imagen de Fondo"

**Resultado:** Mensaje con imagen adjunta

***

### 3️⃣ Configuración Premium Básica (💎 Premium)

**Para:** Servidor que quiere mensajes elegantes y auto-roles

**Pasos en el Dashboard:**

1. Activa el plugin Welcome
2. Activa "Usar Embed"
3. Elige color: Verde (#00ff00)
4. Escribe tu mensaje: `¡Bienvenido {{user}}! Te hemos asignado el rol de **Miembro**.`
5. En "Auto-Roles" selecciona el rol "Miembro"

**Resultado:** Embed verde con rol asignado automáticamente

***

### 4️⃣ Configuración Premium Completa (💎 Premium)

**Para:** Servidor premium con experiencia completa

**Pasos en el Dashboard:**

1. Activa el plugin Welcome
2. Configura el mensaje principal: `⭐ ¡Bienvenido {{user}} a **{{guild}}**! Eres el miembro #{{memberIndex}}.`
3. Activa "Usar Embed" y elige color: Rosa (#ff69b4)
4. Añade imagen de fondo (URL)
5. Activa "Tarjeta Personalizada"
6. En "Auto-Roles" selecciona varios roles (Miembro, Verificado)
7. Activa "Mensaje Directo (DM)"
8. Escribe mensaje DM: `¡Hola {{user}}! Bienvenido a **{{guild}}**. Revisa las reglas en el canal correspondiente.`

**Resultado:** Experiencia de bienvenida completa y profesional con embed, tarjeta, roles y DM

***

## 💡 Casos de Uso Comunes

### 🎮 Servidor de Gaming

**Mensaje recomendado:**

```
🎮 ¡GG {{user}}! Bienvenido a **{{guild}}**!

Ahora somos **{{memberCount}} jugadores**.

📋 Lee las reglas
💬 Únete a chat general
🏆 Revisa los eventos

¡Nos vemos en el juego!
```

**Configuración sugerida:**

* Embed color naranja (#ff4500)
* Auto-Rol: "Jugador"
* Imagen: GIF animado de tu juego

***

### 📚 Servidor Educativo

**Mensaje recomendado:**

```
📚 ¡Bienvenido {{user}} a **{{guild}}**!

Aquí aprenderás junto a {{memberCount}} estudiantes más.

📖 Materiales de estudio
❓ Canal de dudas
👥 Preséntate con nosotros

¡Éxito en tu aprendizaje! 🎓
```

**Configuración sugerida:**

* Embed color azul (#0099ff)
* Auto-Rol: "Estudiante"
* DM con información del curso

***

### 💼 Servidor Profesional/Tech

**Mensaje recomendado:**

```
👋 Bienvenido {{user}} a **{{guild}}**

Eres el miembro #{{memberIndex}} de nuestra comunidad tech.

📋 Código de conducta
💬 Networking
📢 Anuncios importantes
```

**Configuración sugerida:**

* Embed color gris oscuro (#2c2f33)
* Sin auto-roles (verificación manual)
* Imagen corporativa

***

### 🎨 Servidor de Comunidad

**Mensaje recomendado:**

```
✨ ¡Bienvenido {{user}} a **{{guild}}**!

Un espacio para todos.

💬 Chatea en general
🎉 Eventos del servidor
📢 Mantente al día con los anuncios

¡Diviértete! 🌟
```

**Configuración sugerida:**

* Embed color morado (#9b59b6)
* Auto-Rol: "Miembro"
* Tarjeta personalizada

***

## ✅ Mejores Prácticas

### 1. Configuración del Canal

* ✅ **Opción 1 - Configuración Manual:** Al entrar a la configuración del plugin, debes seleccionar un canal específico donde se enviarán los mensajes de bienvenida
* ✅ **Opción 2 - Configuración Automática:** Al activar el plugin por primera vez, puedes marcar "Usar configuración por defecto", y el bot creará automáticamente un canal `#welcome` con permisos preconfigurados
* ✅ En la configuración automática, solo el bot y el owner pueden escribir en el canal por defecto
* ✅ Asegúrate de que el canal sea visible para todos los miembros

### 2. Diseño de Mensajes

* ✅ Usa variables dinámicas para personalización
* ✅ Incluye referencias a canales importantes (`{#channelId}`)
* ✅ Mantén el mensaje conciso pero informativo
* ✅ Usa emojis para dar vida al mensaje
* ✅ Incluye información útil (reglas, canales importantes)

### 3. Auto-Roles (Premium) 🔥

* ✅ Asigna roles básicos automáticamente
* ✅ Verifica que el bot tenga permisos `Manage Roles`
* ✅ El rol del bot debe estar por encima de los roles a asignar
* ✅ No asignes roles de administrador automáticamente
* ✅ Considera roles como: `Miembro`, `Verificado`, `Nuevo`

### 4. Mensajes Directos (Premium) 🔥

* ✅ Mantén los DMs breves y directos
* ✅ Incluye links a reglas y recursos
* ✅ Recuerda que algunos usuarios bloquean DMs
* ✅ El bot maneja automáticamente usuarios con DMs bloqueados

### 5. Tarjetas Personalizadas (Premium) 🔥

* ✅ Usa imágenes de fondo de alta calidad (1920x1080)
* ✅ Las tarjetas incluyen avatar del usuario automáticamente
* ✅ `serverIconDisplay: 'card'` muestra el ícono del servidor
* ✅ Las tarjetas se generan dinámicamente para cada usuario

### 6. Colores de Embeds

* ✅ Elige colores que representen tu comunidad
* ✅ Colores recomendados:
* 💚 Verde: `#00ff00` (acogedor)
* 💙 Azul Discord: `#7289da` (profesional)
* 💜 Morado: `#9b59b6` (elegante)
* 🧡 Naranja: `#ff4500` (energético)
* 💗 Rosa: `#ff69b4` (divertido)
* 💛 Dorado: `#ffd700` (premium)

***

## 🛡️ Solución de Problemas

### ❌ No se envían mensajes de bienvenida

**Causas posibles:**

1. **Plugin deshabilitado**

* ✅ Verifica que el plugin esté activado en el Dashboard
* ✅ Asegúrate de haber guardado los cambios en la configuración

2. **Canal no accesible**

* ✅ Verifica permisos del bot en el canal
* ✅ El bot necesita `Ver Canal` y `Enviar Mensajes`

3. **Bot sin permisos**

* ✅ Revisa permisos del rol del bot
* ✅ Verifica jerarquía de roles

***

### ❌ No se asignan auto-roles (Premium)

**Causas posibles:**

1. **Jerarquía de roles incorrecta**

* ✅ El rol del bot debe estar por encima de los roles a asignar
* ✅ Reordena los roles en Configuración del Servidor

2. **Permiso faltante**

* ✅ El bot necesita `Manage Roles`
* ✅ Verifica en los permisos del rol

3. **IDs de roles incorrectos**

* ✅ Copia los IDs con modo desarrollador activado
* ✅ Verifica que los roles existan

***

### ❌ No se crean tarjetas personalizadas (Premium)

**Causas posibles:**

1. **cardEnabled en false**

* ✅ Asegúrate de que `cardEnabled: true`

2. **imageUrl inválida**

* ✅ La URL debe ser accesible
* ✅ Formatos soportados: PNG, JPG, GIF

3. **Error de generación**

* ✅ Revisa logs del bot
* ✅ El bot hace fallback a imagen estática

***

### ❌ Usuarios no reciben DMs (Premium)

**Esto es normal:**

* 🔥 Algunos usuarios bloquean DMs de bots
* 🔥 El bot maneja esto automáticamente sin errores
  * ✅ El mensaje público sí se enviará

**Si nadie recibe DMs:**

* ✅ Verifica `dmEnabled: true`
* ✅ Comprueba que `dmMessage` tenga contenido

***

### ❌ Variables no se reemplazan

**Causas posibles:**

1. **Sintaxis incorrecta**

* ✅ Usa `{{variable}}` (siempre con dos llaves, ni una ni tres)
* ✅ Revisa mayúsculas/minúsculas

2. **Variable no soportada**

* ✅ Consulta la tabla de [Variables Dinámicas](#variables-dinamicas)
* ✅ Algunas variables son solo Premium

3. **Error de template**

* ✅ Revisa los logs del bot
* ✅ El sistema hace fallback a reemplazos simples

***

### ❌ Referencias a canales no funcionan

**Soluciones:**

1. **Formato incorrecto**

* ✅ Usa `{#channelId}` o `{channel:channelId}`
* ✅ El ID debe tener al menos 5 dígitos

2. **Canal no existe**

* ✅ Verifica que el canal exista en el servidor
* ✅ Copia el ID correcto

***

### ❌ Emojis no se muestran

**Soluciones:**

1. **Emoji del servidor no existe**

* ✅ Usa `{emoji:nombre}` para emojis del servidor
* ✅ Verifica que el emoji exista en tu servidor

2. **Usa emojis estándar**

* ✅ Copia y pega emojis Unicode directamente en tu mensaje: 🔥 👋 ⭐ 💎
* ✅ No necesitas usar la sintaxis `{emoji:}` para emojis comunes

***

## 📑 Comparativa Plan Free vs Premium

| Característica               | Free | Premium 💎 |
| ---------------------------- | ---- | ---------- |
| Mensajes de texto            | ✅    | ✅          |
| Variables dinámicas          | ✅    | ✅          |
| Canal personalizado          | ✅    | ✅          |
| Creación automática de canal | ✅    | ✅          |
| Imágenes                     | ✅    | ✅          |
| Emojis personalizados        | ✅    | ✅          |
| Referencias a canales        | ✅    | ✅          |
| **Embeds personalizados**    | ❌    | ✅          |
| **Color personalizado**      | ❌    | ✅          |
| **Auto-roles**               | ❌    | ✅          |
| **Mensajes directos (DM)**   | ❌    | ✅          |
| **Tarjetas personalizadas**  | ❌    | ✅          |
| **Ícono del servidor**       | ❌    | ✅          |

***

## 📑 Paleta de Colores Recomendada

```
Colores Acogedores:
- Verde Lima:     #00ff00
- Verde Bosque:   #228b22

Colores Profesionales:
- Azul Discord:   #7289da
- Azul Marino:    #1e3a8a

Colores Energéticos:
- Naranja:        #ff4500
- Rojo:    #ff0000

Colores Elegantes:
- Morado:         #9b59b6
- Rosa:           #ff69b4

Colores Premium:
- Dorado:         #ffd700
- Platino:        #e5e4e2
```

***

## 📑 Soporte

Si tienes problemas con el plugin Welcome:

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

***

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

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

***