MANUAL

Telegram Bot

Introducción

Qué es el Canal de Telegram?

El canal de Telegram permite conectar un bot de Telegram con Fararoni, permitiendo que los usuarios interactúen con tu asistente IA a través de la aplicación Telegram.

Arquitectura

+----------------+     +-----------------+     +----------------+     +----------------+
|   Usuario      | --> |  Telegram API   | --> |   Sidecar TG   | --> |   Fararoni     |
|   Telegram     |     |  (Bot Father)   |     |   (:3001)      |     |   Gateway      |
+----------------+     +-----------------+     +----------------+     |   (:7071)      |
                                                                      +----------------+
                                                                             |
                                                                             v
                                                                      +----------------+
                                                                      |  Agentes LLM   |
                                                                      +----------------+

Ventajas de Telegram

Característica	Valor
Costo	GRATIS (sin límites)
API	Oficial y estable
Riesgo de ban	Ninguno
Cifrado	End-to-end
Velocidad	Muy rápida
Setup	5 minutos

Comparativa con WhatsApp

Aspecto	Telegram	WhatsApp Baileys	WhatsApp Enterprise
Costo	Gratis	Gratis	Pago por mensaje
Riesgo de ban	No	Sí	No
API	Oficial	No oficial	Oficial
Setup	5 min	15 min	2-5 días
Usuarios	900M+	2B+	2B+

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 Telegram (en tu celular o escritorio)

Puertos

Puerto	Servicio	Estado Requerido
7071	Gateway REST	Abierto (local)
3001	Sidecar Telegram	Abierto (local)

Verificar Requisitos

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

# Verificar npm
npm --version

# Verificar Java
java --version

Cifrado de Canales (Encryption Key)

Los tokens del bot se almacenan cifrados en la base de datos local.

Escenario	Key env var	DEV_MODE	Resultado
Producción con key	`"abc123..."`	`false`	Usa la key del env
Producción sin key	(vacía)	`false`	LOG.severe advierte, sin cifrado
Desarrollo con key	`"abc123..."`	`true`	Usa la key del env
Desarrollo sin key	(vacía)	`true`	Auto-genera key AES-256 persistente

# Producción
export FARARONI_CHANNELS_ENCRYPTION_KEY="$(openssl rand -base64 32)"
export FARARONI_ENV=production

# Desarrollo local (no requiere configuración extra)
export FARARONI_DEV_MODE=true

Crear Bot en Telegram

Paso 3.1: Abrir BotFather

Abre Telegram en tu celular o escritorio
En el buscador, escribe @BotFather
Selecciona el usuario con la marca de verificación azul
Inicia una conversación (click en "Start")

Paso 3.2: Crear Nuevo Bot

Envía el comando: /newbot

BotFather te pedirá el nombre visible (ej: Fararoni Asistente) y luego el username (ej: mi_asistente_bot).

IMPORTANTE: El username DEBE terminar en bot y debe ser único en todo Telegram.

Paso 3.3: Obtener el Token

BotFather te dará un mensaje con tu token:

Use this token to access the HTTP API:
1234567890:ABCdefGHIjklMNOpqrSTUvwxYZ

COPIA Y GUARDA ESTE TOKEN — Lo necesitarás para iniciar el Sidecar.

IMPORTANTE: El token es secreto. NUNCA lo compartas públicamente ni lo subas a git.

Recuperar Token Existente

Si ya creaste un bot antes: envía /mybots a @BotFather, selecciona tu bot y click en API Token.

Regenerar Token Comprometido

Envía /revoke a @BotFather, selecciona tu bot. El anterior dejará de funcionar inmediatamente.

Instalar el Sidecar

cd /ruta/a/fararoni/fararoni-sidecar-tg
npm install

Esto instalará: telegraf, express, axios, dotenv

# Verificar instalación
ls node_modules | wc -l
# Debe mostrar un número mayor a 0

Configurar Fararoni

Verificar modules.yml

Ubicación: ~/.fararoni/config/modules.yml

channels:
  telegram:
    enabled: true
    trust_level: SECURE_ENCRYPTED
    egress_url: "http://localhost:3001/send"
    capabilities:
      - text
    timeout_ms: 5000
    retry_count: 3

Verificar Gateway REST

gateway:
  rest:
    enabled: true
    port: 7071

Puesta en Marcha

Resumen Rápido

Terminal 1: java --enable-preview -jar fararoni-core-1.0.0.jar --server
Terminal 2: export TELEGRAM_TOKEN="tu_token" && npm start
Telegram:   Buscar tu bot y enviar mensaje

Orden de Inicio (IMPORTANTE)

1. Fararoni Core (Gateway)  <-- PRIMERO (puerto 7071)
2. Sidecar Telegram         <-- SEGUNDO (puerto 3001)

El Sidecar necesita conectarse al Gateway. Si el Gateway no está corriendo, el Sidecar fallará con error ECONNREFUSED.

Terminal 1: Iniciar Fararoni Core

cd fararoni-core/target
java --enable-preview -jar fararoni-core-1.0.0.jar --server

Esperar hasta ver:

[MODULE-REGISTRY] Loaded module: OmniChannelGatewayModule
[INGRESS] RestIngressServer listening on port 7071
[READY] Fararoni Core listo

Terminal 2: Iniciar Sidecar Telegram

cd fararoni-sidecar-tg
export TELEGRAM_TOKEN="1234567890:ABCdefGHIjklMNOpqrSTUvwxYZ"
npm start

Esperar hasta ver:

[INFO]  [HTTP] Servidor Egress en puerto 3001
[INFO]  [TELEGRAM] Bot conectado: @tu_bot_username
[INFO]  [READY] Sidecar listo para recibir mensajes

Alternativa: Usar Archivo .env

cd fararoni-sidecar-tg
cp .env.example .env
nano .env

TELEGRAM_TOKEN=1234567890:ABCdefGHIjklMNOpqrSTUvwxYZ
SIDECAR_PORT=3001
GATEWAY_URL=http://localhost:7071/gateway/v1/inbound
DEBUG=false

Verificar Funcionamiento

Health Check del Gateway

curl http://localhost:7071/gateway/v1/health

{"status": "healthy", "module": "gateway-rest-omnichannel"}

Health Check del Sidecar

curl http://localhost:3001/health

{
  "status": "healthy",
  "service": "fararoni-sidecar-tg",
  "channel": "telegram",
  "port": 3001,
  "bot": {
    "id": 1234567890,
    "username": "tu_bot_username"
  }
}

Prueba End-to-End

Abre Telegram
Busca tu bot: @tu_bot_username
Inicia conversación (click en "Start" o envía /start)
Envía: Hola, qué puedes hacer?
Deberías recibir una respuesta del asistente Fararoni

Verificar Logs

[INFO]  [INGRESS] 123456789 -> "Hola, que puedes hacer?" (HTTP 202)
[INFO]  [EGRESS] 123456789 <- "Hola! Soy Fararoni, tu asistente..."

Seguridad

Filtro de Grupos

Por defecto, el sidecar SOLO responde a chats privados (1:1).

Tipo de Chat	Procesado?
Privado (1:1)	SÍ
Grupo	NO
Supergrupo	NO
Canal	NO

Habilitar Grupos Específicos

const ALLOWED_GROUPS = ['-123456789', '-987654321'];

if (chat.type !== 'private' && !ALLOWED_GROUPS.includes(chat.id.toString())) {
    logger.debug(`[FILTRO] Ignorando mensaje de ${chat.type}: ${chat.id}`);
    return;
}

Proteger el Token

NUNCA subas el token a git
Usa variables de entorno o archivo .env
El archivo .env debe estar en .gitignore

Si tu token fue comprometido: abre @BotFather, envía /revoke, selecciona tu bot.

Control de Acceso

Opción A: Bot Público — Cualquiera puede chatear (comportamiento por defecto).

Opción B: Restringir Usuarios — Obtén tu User ID con @userinfobot y configura:

const ALLOWED_USERS = [
    '123456789',    // Tu User ID
    '987654321',    // Otro usuario permitido
];

if (ALLOWED_USERS.length > 0 && !ALLOWED_USERS.includes(senderId.toString())) {
    logger.debug(`[FILTRO] Usuario no autorizado: ${senderId}`);
    return;
}

Troubleshooting

El bot no responde

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

# Verificar Sidecar
curl http://localhost:3001/health

Si ves 401 Unauthorized en logs, el token es inválido. Regenera con /token en @BotFather.

Error "ECONNREFUSED"

Causa: El Gateway no está corriendo.

java --enable-preview -jar fararoni-core-1.0.0.jar --server

Error "401 Unauthorized"

Token inválido o expirado. En @BotFather envía /token, copia el nuevo y reinicia el sidecar.

Error "409 Conflict: terminated by other getUpdates"

Causa: Otro proceso está usando el mismo bot. Cierra cualquier otra instancia del sidecar.

El bot responde en grupos

Verifica que index.js tenga el filtro:

if (chat.type !== 'private') {
    return;
}

Mensajes llegan pero no hay respuesta

Verificar logs de Fararoni Core, buscar errores en OmniChannelRouter, confirmar API key del LLM.

Comandos Útiles

Health Checks

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

# Sidecar Telegram
curl http://localhost:3001/health

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

Ver Logs en Tiempo Real

tail -f ~/.fararoni/logs/fararoni.log | grep -E "(OmniChannel|TELEGRAM)"

Detener Servicios

# Detener Gateway
pkill -f "fararoni-core"

# Detener Sidecar
pkill -f "fararoni-sidecar-tg"

Comandos de BotFather

/token          - Ver token actual
/setname        - Cambiar nombre del bot
/setdescription - Cambiar descripción
/revoke         - Regenerar token

Anexos

Checklist de Implementación

REQUISITOS
[ ] Node.js 18+ instalado
[ ] Fararoni Core instalado
[ ] Java 25+ con --enable-preview

TELEGRAM
[ ] Bot creado en @BotFather
[ ] Token guardado de forma segura

INSTALACIÓN
[ ] npm install ejecutado
[ ] .env creado con TELEGRAM_TOKEN
[ ] modules.yml tiene telegram.enabled: true

PUESTA EN MARCHA
[ ] Gateway corriendo en puerto 7071
[ ] Sidecar corriendo en puerto 3001
[ ] Health checks OK

PRUEBAS
[ ] Mensaje enviado desde Telegram
[ ] Respuesta recibida del asistente

Configuración Avanzada

# Cambiar puerto del sidecar
export SIDECAR_PORT=3002
npm start

Actualizar modules.yml:

channels:
  telegram:
    egress_url: "http://localhost:3002/send"

Múltiples Bots

channels:
  telegram_ventas:
    enabled: true
    egress_url: "http://localhost:3001/send"

  telegram_soporte:
    enabled: true
    egress_url: "http://localhost:3002/send"

Autor: Equipo Fararoni | Versión: 1.0