MANUAL

Discord Bot

Introducción

Qué es el Canal de Discord?

El canal de Discord permite conectar un bot de Discord con Fararoni, permitiendo que los usuarios interactúen con tu asistente IA a través de la aplicación Discord, tanto en mensajes directos (DMs) como en servidores.

Arquitectura

+----------------+     +-----------------+     +----------------+     +----------------+
|   Usuario      | --> |   Discord API   | --> |  Sidecar DC    | --> |   Fararoni     |
|   Discord      |     |   (Bot Gateway) |     |   (:3002)      |     |   Gateway      |
+----------------+     +-----------------+     +----------------+     |   (:7071)      |
                                                                      +----------------+
                                                                             |
                                                                             v
                                                                      +----------------+
                                                                      |  Agentes LLM   |
                                                                      +----------------+

Ventajas de Discord

Característica	Valor
Costo	GRATIS
API	Oficial y estable
Riesgo de ban	Ninguno
Rate limits	Generosos
Velocidad	Muy rápida
Setup	10 minutos
Comunidad	Ideal para gaming/dev

Comparativa con Otros Canales

Aspecto	Discord	Telegram	WhatsApp Baileys
Costo	Gratis	Gratis	Gratis
Riesgo de ban	No	No	Sí
API	Oficial	Oficial	No oficial
Setup	10 min	5 min	15 min
Servidores/Grupos	Sí (con mención)	Solo DMs	Solo DMs
Rich embeds	Sí	No	No

Requisitos Previos

Software Necesario

Node.js 18 o superior
npm (viene con Node.js)
Fararoni Core instalado
Java 25+ con --enable-preview

Cuentas

Cuenta de Discord
Acceso al Discord Developer Portal

Puertos

Puerto	Servicio	Estado Requerido
7071	Gateway REST	Abierto (local)
3002	Sidecar Discord	Abierto (local)

Verificar Requisitos

# Verificar Node.js (debe ser 18+)
node --version

# Verificar npm
npm --version

# Verificar Java
java --version

# Verificar que Fararoni esté corriendo
curl http://localhost:7071/gateway/v1/health

Crear Bot en Discord

Paso 3.1: Acceder al Developer Portal

Abre tu navegador
Ve a: https://discord.com/developers/applications
Inicia sesión con tu cuenta de Discord
Click en "New Application" (botón azul, esquina superior derecha)

Paso 3.2: Crear la Aplicación

Ingresa un nombre para tu aplicación (ej: Fararoni Bot)
Acepta los términos de servicio
Click en "Create"

Paso 3.3: Crear el Bot

En el menú lateral izquierdo, click en "Bot"
Click en "Add Bot"
Confirma clickeando "Yes, do it!"

Paso 3.4: Configurar Intents (MUY IMPORTANTE)

En la misma página de Bot, baja hasta "Privileged Gateway Intents" y activa:

MESSAGE CONTENT INTENT (OBLIGATORIO)
PRESENCE INTENT (opcional)
SERVER MEMBERS INTENT (opcional)

CRÍTICO: Sin "Message Content Intent", el bot recibirá mensajes VACÍOS.

Click en "Save Changes" al final de la página.

Paso 3.5: Obtener el Token

En la sección "Bot", busca "Token"
Click en "Reset Token" o "Copy"
GUARDA ESTE TOKEN en un lugar seguro

Ejemplo de token (NO uses este):
MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.GrWvSg.abcdefghijklmnopqrstuvwxyz123456

ADVERTENCIA: Nunca compartas tu token. Si lo expones, regénéralo en el Developer Portal.

Paso 3.6: Invitar el Bot a tu Servidor

En el menú lateral, click en "OAuth2" -> "URL Generator"
En "SCOPES", selecciona: bot
En "BOT PERMISSIONS": Send Messages, Read Message History, View Channels
Copia la URL generada, ábrela en tu navegador
Selecciona el servidor y click en "Authorize"

Instalar el Sidecar

Paso 4.1: Ubicar el Directorio

cd fararoni-sidecar-discord

Paso 4.2: Instalar Dependencias

npm install

Esto instalará: discord.js, express, axios, dotenv

Paso 4.3: Crear Archivo de Configuración

# Copiar el archivo de ejemplo
cp .env.example .env

# Editar con tu editor favorito
nano .env

Paso 4.4: Configurar Variables

Edita el archivo .env:

# Token del bot de Discord (REQUERIDO)
DISCORD_TOKEN=MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.GrWvSg.tu_token_aqui

# URL del Gateway REST de Fararoni
GATEWAY_URL=http://localhost:7071/gateway/v1/inbound

# Puerto del servidor HTTP para Egress
SIDECAR_PORT=3002

# Permitir mensajes en servidores (requiere mención del bot)
ALLOW_GUILDS=false

# Lista de IDs de usuarios permitidos (separados por coma)
ALLOWED_USERS=

# Modo debug
DEBUG=false

Configurar Fararoni

Verificar Gateway

Verifica en ~/.fararoni/config/modules.yml:

gateway:
  rest:
    enabled: true
    port: 7071

channels:
  discord:
    enabled: true
    egress_url: "http://localhost:3002/send"

Reiniciar Fararoni

# Si Fararoni está corriendo, el Hot Reload debería detectar cambios
# Si no, reinicia el servidor
./start-server.sh

Puesta en Marcha

Prerequisitos

Crear bot en Discord Developer Portal (Sección 3)
Activar MESSAGE CONTENT INTENT (Paso 3.4)
Obtener y guardar el token en .env (Paso 3.5)
Instalar dependencias con npm install (Sección 4)

Paso 6.1: Iniciar Fararoni Gateway

# Terminal 1: Fararoni Core
cd /ruta/a/fararoni
./start-server.sh

Nota: El Gateway debe estar corriendo en el puerto configurado (por defecto 7071).

Paso 6.2: Iniciar el Sidecar Discord

# Terminal 2: Sidecar Discord
cd fararoni-sidecar-discord
npm start

Salida Esperada

============================================================
  FARARONI SIDECAR - DISCORD (FASE 71.6)
============================================================

[INFO]  12:34:56 [HTTP] Servidor Egress en puerto 3002
[INFO]  12:34:57 [DISCORD] Bot conectado: FararoniBot#1234
[INFO]  12:34:57 [DISCORD] Servidores: 2
[INFO]  12:34:57 [GATEWAY] Enviando a: http://localhost:7071/gateway/v1/inbound
[INFO]  12:34:57 [SEGURIDAD] Solo DMs (mensajes directos)
[INFO]  12:34:57 [READY] Sidecar listo para recibir mensajes

------------------------------------------------------------

Para modo debug: npm run dev o DEBUG=true npm start

Verificar Funcionamiento

Invitar el Bot a un Servidor

IMPORTANTE: No puedes buscar un bot nuevo en Discord si no compartes un servidor con él. Primero invita el bot a un servidor.

Abre Discord y crea un servidor de pruebas (botón +)
Ve a https://discord.com/developers/applications → tu app → "OAuth2" → "URL Generator"
En SCOPES marca bot; en BOT PERMISSIONS marca Send Messages, Read Message History, View Channels
Copia la URL, ábrela, selecciona tu servidor y autoriza

Test de Mensaje Directo (DM)

IMPORTANTE: Debes abrir una conversación privada (DM) con el bot, no escribir en el canal del servidor.

En el panel de miembros, busca tu bot con etiqueta "BOT"
Click derecho → "Message"
Escribe: Hola y presiona Enter

Verificar en Terminal

[INFO]  15:45:xx [INGRESS] TuUsuario (DM) -> "Hola" (HTTP 202)
[INFO]  15:45:xx [EGRESS] 123456789 <- "Hola! En que puedo ayudarte?"

DMs en Discord

Regla del "Primer Contacto": Discord no permite enviar DMs a un bot sin compartir un servidor. Usa el servidor como puente temporal. Una vez creado el DM, accede desde el icono de Discord (Home) → Mensajes Directos.

El sidecar detecta automáticamente el origen:

conversationId: msg.guildId || 'dm'

Health Check

curl http://localhost:3002/health

{
  "status": "healthy",
  "service": "fararoni-sidecar-discord",
  "channel": "discord",
  "port": 3002,
  "bot": {
    "id": "123456789012345678",
    "username": "FararoniBot",
    "tag": "FararoniBot#1234"
  }
}

Modos de Operación

Modo DM (Por Defecto)

El bot SOLO responde a mensajes directos.

# .env
ALLOW_GUILDS=false

Modo DM + Servidores (con Mención)

El bot responde a DMs y a mensajes en servidores solo si lo mencionan.

# .env
ALLOW_GUILDS=true

Modo Restringido (Allowlist)

# .env
ALLOWED_USERS=123456789012345678,987654321098765432

Cómo obtener tu User ID:

En Discord → Configuración → Avanzado
Activa "Modo desarrollador"
Click derecho en cualquier usuario → "Copiar ID"

Seguridad

Protección del Token

NUNCA: Subas el token a GitHub, compartas el token en chats, incluyas el token en código fuente.

SIEMPRE: Usa archivos .env (están en .gitignore), regenera el token si lo expones, usa variables de entorno en producción.

Filtros de Seguridad

Filtro	Descripción
Anti-bot	Ignora mensajes de otros bots
Anti-loop	Ignora sus propios mensajes
Guild filter	Solo responde en servidores si lo mencionan
Allowlist	Restringe usuarios autorizados

Regenerar Token Comprometido

Ve a https://discord.com/developers/applications
Selecciona tu aplicación → "Bot" → "Reset Token"
Actualiza .env y reinicia el sidecar

Troubleshooting

Error: "TOKEN_INVALID"

Causa: Token incorrecto o regenerado. Solución: Copia el token correcto del Developer Portal, actualiza .env y reinicia.

Error: "Used disallowed intents"

Causa: No activaste "Privileged Gateway Intents".

Developer Portal → tu app → "Bot"
Activa MESSAGE CONTENT INTENT
Click "Save Changes" y reinicia el sidecar

Error: "ECONNREFUSED" al Gateway

# Verificar Gateway
curl http://localhost:7071/gateway/v1/health

# Si no responde, iniciar Fararoni
./start-server.sh

# Verificar URL en .env
cat .env | grep GATEWAY_URL

El bot no responde en servidores

Cambia ALLOW_GUILDS=true en .env, reinicia y menciona al bot: @FararoniBot hola.

Puerto 3002 ocupado (EADDRINUSE)

lsof -i :3002
kill -9 <PID>
# O cambiar puerto: SIDECAR_PORT=3003

Si cambias el puerto, actualiza egress_url en modules.yml.

Comandos Útiles

Iniciar el Sidecar

# Normal
npm start

# Con debug
npm run dev

# Con variables inline
DISCORD_TOKEN=xxx GATEWAY_URL=http://localhost:7071/gateway/v1/inbound node index.js

Verificar Estado

# Health check
curl http://localhost:3002/health

# Estado detallado
curl http://localhost:3002/status

Logs y Procesos

# Ver logs en tiempo real
npm start 2>&1 | tee discord.log

# Ver procesos del sidecar
ps aux | grep "node index.js"

# Matar proceso
pkill -f "fararoni-sidecar-discord"

Apéndices

Estructura del Proyecto

fararoni-sidecar-discord/
├── index.js          # Código principal del sidecar
├── package.json      # Dependencias y scripts
├── .env.example      # Plantilla de configuración
├── .env              # Configuración local (no subir a git)
└── node_modules/     # Dependencias instaladas

Flujo de Mensajes

1. Usuario envía "Hola" por Discord DM
2. Discord API notifica al bot (WebSocket)
3. Sidecar recibe evento messageCreate
4. Filtros de seguridad validan el mensaje
5. Sidecar envía POST a Gateway (:7071/gateway/v1/inbound)
6. Gateway publica en SovereignEventBus
7. OmniChannelRouter enruta al agente
8. Agente genera respuesta con LLM
9. Gateway envía POST al Sidecar (:3002/send)
10. Sidecar envía respuesta a Discord API
11. Usuario ve la respuesta en Discord

Esquema UniversalMessage

{
  "messageId": "dc-1234567890",
  "channelId": "discord",
  "senderId": "1234567890123456789",
  "conversationId": "dm",
  "type": "TEXT",
  "textContent": "Hola, como estás?",
  "metadata": {
    "profileName": "Usuario123",
    "globalName": "Usuario",
    "discriminator": "1234",
    "userId": "9876543210987654321",
    "isDM": true,
    "guildName": null
  },
  "timestamp": "2026-02-20T12:34:56.789Z"
}

Documento generado para FASE 71.6 - Fararoni Sidecar Discord