28 KiB
Executable File
28 KiB
Executable File
Documentación Técnica del Sistema de Bots de Mensajería
1. Visión General del Sistema
Este es un sistema de mensajería multiplataforma desarrollado en PHP que permite gestionar y enviar notificaciones automatizadas a través de Discord y Telegram. El sistema incluye:
- Programación de mensajes (una vez o recurrentes)
- Traducción automática mediante LibreTranslate
- Galería de imágenes para usar en mensajes
- Plantillas de mensajes recurrentes
- Panel de administración completo
- Integración con n8n para automatización/IA
2. Tecnologías y Herramientas Utilizadas
Backend
- PHP 8.3+ - Lenguaje principal del servidor
- MySQL 9.5+ - Base de datos relacional
- Composer - Gestión de dependencias PHP
APIs y Servicios Externos
- Discord API v10 - Bot de Discord (librería discord-php)
- Telegram Bot API - Envío de mensajes via HTTP
- LibreTranslate - Servicio de traducción automática
- n8n - Plataforma de automatización (webhooks para IA)
Frontend
- Bootstrap 5.3 - Framework CSS responsivo
- Bootstrap Icons - Iconos
- Summernote - Editor WYSIWYG para mensajes HTML
- jQuery - Manipulación del DOM
Infraestructura
- Zone Horaria: America/Mexico_City (UTC-6)
- Entornos: pruebas, reod (producción)
- Sistema de Logs: Monolog + logs nativos PHP
3. Estructura de Archivos del Proyecto
/var/www/html/bot/
├── index.php # Dashboard principal
├── login.php # Página de inicio de sesión
├── logout.php # Cerrar sesión
├── profile.php # Perfil del usuario
│
├── create_message.php # Crear nuevo mensaje
├── edit_message.php # Editar mensaje existente
├── scheduled_messages.php # Ver mensajes programados
├── sent_messages.php # Ver mensajes enviados
├── recurrentes.php # Gestionar plantillas recurrentes
├── preview_message.php # Previsualizar mensaje
├── enviar_plantilla.php # Enviar plantilla a usuarios
│
├── gallery.php # Galería de imágenes
├── upload.php # Subir imágenes
├── delete_image.php # Eliminar imágenes
├── rename_image.php # Renombrar imágenes
├── upload_editor_image.php # Subir imágenes desde editor
│
├── change_language.php # Cambiar idioma de la interfaz
│
├── discord_bot.php # Bot de Discord (proceso largo)
├── telegram_bot_webhook.php # Webhook de Telegram
├── process_queue.php # Procesador de cola de mensajes
│
├── config/
│ └── config.php # Configuración principal
│
├── includes/ # Archivos incluidos
│ ├── db.php # Conexión a base de datos
│ ├── session_check.php # Verificación de sesión
│ ├── auth.php # Autenticación
│ ├── logger.php # Funciones de logging
│ ├── activity_logger.php # Registro de actividades
│ ├── message_handler.php # Procesamiento de mensajes
│ ├── message_handler_edit.php
│ ├── schedule_helpers.php # Funciones de programación
│ ├── schedule_actions.php # Acciones de programación
│ ├── recurrent_message_handler.php
│ ├── translation_helper.php # Helper de traducción
│ ├── url_helper.php # Helper de URLs
│ ├── emojis.php # Emojis disponibles
│ ├── get_gallery.php # Obtener imágenes galería
│ ├── error_handler.php # Manejo de errores
│ ├── telegram_actions.php # Acciones de Telegram
│ ├── discord_actions.php # Acciones de Discord
│ ├── tren_handler.php # Manejo de eventos de tren
│ ├── command_locker.php # Bloqueo de comandos
│ └── get_chat_history.php # Historial de chat
│
├── src/ # Clases principales
│ ├── Translate.php # Clase de traducción
│ ├── TelegramSender.php # Envío a Telegram
│ ├── DiscordSender.php # Envío a Discord
│ ├── HtmlToTelegramHtmlConverter.php
│ ├── HtmlToDiscordMarkdownConverter.php
│ ├── TranslationWorker.php # Worker de traducción
│ ├── TranslationCache.php # Cache de traducciones
│ ├── CommandLocker.php # Bloqueo de comandos
│ └── TranslationWorkerPool.php
│
├── discord/ # Módulo Discord
│ ├── DiscordSender.php
│ ├── converters/
│ │ └── HtmlToDiscordMarkdownConverter.php
│ └── actions/
│ └── discord_actions.php
│
├── telegram/ # Módulo Telegram
│ ├── TelegramSender.php
│ ├── converters/
│ │ └── HtmlToTelegramHtmlConverter.php
│ ├── actions/
│ │ ├── telegram_actions.php
│ │ └── send_telegram_reply.php
│ ├── admin/
│ │ ├── telegram_bot_interactions.php
│ │ ├── telegram_welcome.php
│ │ └── chat_telegram.php
│ └── webhook/
│ └── telegram_bot_webhook.php
│
├── admin/ # Panel de Administración
│ ├── users.php # Gestión de usuarios
│ ├── recipients.php # Gestión de destinatarios
│ ├── languages.php # Gestión de idiomas
│ ├── comandos.php # Gestión de comandos
│ ├── activity.php # Ver actividad del sistema
│ ├── test_discord_connection.php
│ ├── set_test_webhook.php
│ ├── sync_languages.php # Sincronizar idiomas
│ ├── get_user_groups.php
│ ├── update_language_status.php
│ └── update_language_flag.php
│
├── templates/ # Plantillas UI
│ ├── header.php # Encabezado con menú
│ └── footer.php # Pie de página
│
├── galeria/ # Imágenes del sistema
│
├── db/
│ └── bot.sql # Esquema de base de datos
│
├── logs/ # Archivos de log
│ ├── discord_bot.log
│ ├── telegram_bot_webhook.log
│ ├── process_queue.log
│ └── php_errors.log
│
├── vendor/ # Dependencias Composer
└── config/ # Configuraciones adicionales
4. Estructura de la Base de Datos
Tablas Principales
users - Usuarios del sistema
id(INT, PK)username(VARCHAR)password(VARCHAR, hashed)role(ENUM: 'user', 'admin')telegram_chat_id(VARCHAR, nullable)created_at(TIMESTAMP)
recipients - Destinatarios (canales/usuarios)
id(INT, PK)platform_id(BIGINT) - ID en Discord/Telegramname(VARCHAR)type(ENUM: 'channel', 'user')platform(ENUM: 'discord', 'telegram')language_code(VARCHAR, default 'es')chat_mode(VARCHAR) - Modo de chat: agent, bot, iacreated_at(TIMESTAMP)
messages - Contenido de mensajes
id(INT, PK)user_id(INT, FK)content(TEXT) - HTML del mensajecreated_at(TIMESTAMP)
schedules - Programaciones de envío
id(INT, PK)message_id(INT, FK)recipient_id(INT, FK)send_time(DATETIME)status(ENUM: 'draft', 'pending', 'processing', 'sent', 'failed')is_recurring(BOOLEAN)recurring_days(VARCHAR) - Días separados por comarecurring_time(TIME)sent_at(DATETIME)error_message(TEXT)created_at(TIMESTAMP)
recurrent_messages - Plantillas de mensajes
id(INT, PK)name(VARCHAR)message_content(TEXT)telegram_command(VARCHAR) - Comando sin #created_at(TIMESTAMP)updated_at(TIMESTAMP)
sent_messages - Mensajes enviados
id(INT, PK)schedule_id(INT, FK)recipient_id(INT, FK)platform_message_id(VARCHAR) - ID del mensaje en plataformamessage_count(INT)sent_at(DATETIME)
supported_languages - Idiomas disponibles
id(INT, PK)language_code(VARCHAR) - Código (es, pt, en, etc.)language_name(VARCHAR) - Nombre del idiomaflag_emoji(VARCHAR) - Emoji de banderais_active(BOOLEAN) - Si está activo para traduccióncreated_at(TIMESTAMP)updated_at(TIMESTAMP)
telegram_bot_messages - Configuración de Bienvenida Telegram
id(INT, PK)message_text(TEXT) - Mensaje de bienvenida (soporta {user_name})button_text(VARCHAR) - Texto del botóngroup_invite_link(VARCHAR) - Enlace de invitación al grupois_active(BOOLEAN) - Si el mensaje está activoregister_users(BOOLEAN) - Si se registran automáticamente los usuariosupdated_at(TIMESTAMP)
telegram_bot_interactions - Registro de Interacciones Telegram
id(INT, PK)user_id(BIGINT) - ID del usuario en Telegramusername(VARCHAR) - Username de Telegramfirst_name(VARCHAR) - Nombre del usuariolast_name(VARCHAR) - Apellido del usuariointeraction_type(VARCHAR) - Tipo: 'message', 'start', etc.interaction_date(TIMESTAMP)
settings - Configuraciones Generales
setting_key(VARCHAR, PK)setting_value(VARCHAR)
telegram_welcome_messages - Mensajes de Bienvenida por Grupo
id(INT, PK)chat_id(BIGINT) - ID del grupo de Telegramwelcome_message(TEXT) - Mensaje personalizadobutton_text(VARCHAR)group_invite_link(VARCHAR)is_active(BOOLEAN)created_at(TIMESTAMP)updated_at(TIMESTAMP)language_code(VARCHAR)language_name(VARCHAR)flag_emoji(VARCHAR)is_active(BOOLEAN)created_at(TIMESTAMP)
translation_queue - Cola de traducciones
id(INT, PK)platform(VARCHAR)message_id(BIGINT)chat_id(BIGINT)user_id(BIGINT)text_to_translate(TEXT)source_lang(VARCHAR)target_lang(VARCHAR)status(ENUM: 'pending', 'completed', 'failed')created_at(TIMESTAMP)
activity_log - Registro de actividades
id(INT, PK)user_id(INT)username(VARCHAR)action(VARCHAR)details(TEXT)timestamp(DATETIME)
telegram_interactions - Interacciones Telegram
id(INT, PK)chat_id(BIGINT)message_text(TEXT)direction(ENUM: 'in', 'out')language_code(VARCHAR)created_at(TIMESTAMP)
command_locks - Bloqueos de comandos
id(INT, PK)chat_id(BIGINT)command(VARCHAR)type(ENUM: 'command', 'translation')data(JSON)message_id(BIGINT)status(ENUM: 'processing', 'completed', 'failed')created_at(TIMESTAMP)expires_at(DATETIME)
5. Análisis del Menú y Rutas
5.1 Menú Principal (templates/header.php)
├── INICIO (index.php)
│ └── Dashboard - Vista de mensajes programados del usuario
│
├── MENSAJES (dropdown)
│ ├── Crear Mensaje (create_message.php)
│ │ ├── Carga plantillas
│ │ ├── Editor HTML (Summernote)
│ │ ├── Selección de plataforma (Discord/Telegram)
│ │ ├── Selección de destinatario
│ │ ├── Programación (ahora/fecha/recurrente)
│ │ └── Envío → includes/message_handler.php
│ │
│ ├── Programados (scheduled_messages.php)
│ │ └── Lista de mensajes pendientes/enviados
│ │
│ ├── Plantillas (recurrentes.php)
│ │ ├── Crear plantilla
│ │ ├── Editor HTML
│ │ ├── Comando Telegram (sin #)
│ │ └── includes/recurrent_message_handler.php
│ │
│ └── Enviados (sent_messages.php)
│ └── Historial de mensajes enviados
│
├── GALERÍA (gallery.php)
│ ├── Ver todas las imágenes
│ ├── Subir imagen → upload.php
│ ├── Renombrar → rename_image.php
│ └── Eliminar → delete_image.php
│
├── ADMIN (solo admins)
│ ├── Gestión
│ │ ├── Usuarios (admin/users.php)
│ │ │ ├── Crear usuario
│ │ │ ├── Editar usuario
│ │ │ ├── Asignar rol (user/admin)
│ │ │ └── Vincular Telegram
│ │ │
│ │ └── Destinatarios (admin/recipients.php)
│ │ ├── Listar canales/usuarios Discord
│ │ ├── Listar canales/usuarios Telegram
│ │ ├── Editar idioma
│ │ └── Eliminar destinatario
│ │
│ ├── Configuración
│ │ ├── Idiomas (admin/languages.php)
│ │ │ ├── Lista de idiomas soportados
│ │ │ ├── Activar/desactivar idioma
│ │ │ ├── Editar bandera emoji
│ │ │ └── Sincronizar con LibreTranslate
│ │ │
│ │ └── Comandos (admin/comandos.php)
│ │ └── Lista de comandos disponibles
│ │
│ ├── Bots (Telegram)
│ │ ├── Config (telegram/admin/telegram_welcome.php)
│ │ │ └── Configurar mensaje de bienvenida
│ │ │
│ │ ├── Interacciones Bot (telegram/admin/telegram_bot_interactions.php)
│ │ │ └── Ver interacciones de usuarios
│ │ │
│ │ └── Chat Telegram (telegram/admin/chat_telegram.php)
│ │ └── Ver historial de chat
│ │
│ └── Monitoreo
│ ├── Actividad (admin/activity.php)
│ │ └── Log de actividades del sistema
│ │
│ └── Test (admin/test_discord_connection.php)
│ └── Probar conexión con Discord
│
├── PERFIL (profile.php)
│ └── Configuración de cuenta de usuario
│
└── CERRAR SESIÓN (logout.php)
6. Flujo de Funcionamiento
6.1 Creación y Envío de Mensaje
1. Usuario inicia sesión (login.php)
└── Valida credenciales → includes/auth.php
└── Crea sesión PHP
2. Usuario crea mensaje (create_message.php)
├── Selecciona plantilla (opcional)
├── Escribe/edita contenido HTML (Summernote)
├── Selecciona plataforma (Discord/Telegram)
├── Selecciona destinatario(s)
├── Selecciona programación:
│ ├── Enviar ahora
│ ├── Programar para fecha/hora
│ └── Programación recurrente (días + hora)
└── Envía formulario
3. Procesamiento (includes/message_handler.php)
├── Valida datos
├── Inserta mensaje en tabla `messages`
├── Inserta programación en tabla `schedules`
└── Si es "enviar ahora":
└── Ejecuta process_queue.php en background
4. Cola de procesamiento (process_queue.php)
├── Se ejecuta cada minuto (cron job)
├── Busca mensajes pending con send_time <= ahora
├── Marca como 'processing'
├── Convierte HTML a formato de plataforma:
│ ├── Discord → DiscordSender + HtmlToDiscordMarkdownConverter
│ └── Telegram → TelegramSender + HtmlToTelegramHtmlConverter
├── Envía mensaje a API de plataforma
├── Registra en `sent_messages`
├── Si es recurrente, calcula próximo envío
└── Marca como 'sent' o 'failed'
5. Usuario puede ver:
├── Mensajes programados (scheduled_messages.php)
├── Mensajes enviados (sent_messages.php)
└── Plantillas guardadas (recurrentes.php)
6.2 Flujo de Traducción Automática
1. Mensaje se crea con atributo data-translate="true"
→ Se encola para traducción
2. Translation Worker (process_translation_queue.php)
├── Detecta idioma original (LibreTranslate /detect)
├── Traduce a cada idioma activo (LibreTranslate /translate)
├── Guarda en translation_queue
└── Envía resultado a usuario
3. Botones de traducción en Telegram
├── Se añaden después de enviar mensaje
├── Callback: translate:{message_id}:{lang}
└── Usuario puede traducir manualmente
4. Botones de traducción en Discord
├── Se añaden después de enviar mensaje
├── Botones con estilo: translate_manual:{lang}
└── Traducción inline en canal
7. Bots de Mensajería
7.1 Bot de Discord (discord_bot.php)
Tecnologías:
- Librería
discord-php(v7+) - WebSockets para eventos en tiempo real
- API REST para envío de mensajes
Eventos manejados:
| Evento | Acción |
|---|---|
GUILD_MEMBER_ADD |
Registra nuevo miembro en recipients |
MESSAGE_CREATE |
Procesa mensajes entrantes |
INTERACTION_CREATE |
Maneja clics en botones |
Comandos disponibles:
| Comando | Descripción |
|---|---|
#comando |
Envía plantilla de mensaje |
/comandos |
Lista de comandos disponibles |
/setlang XX |
Establece idioma del usuario |
/bienvenida |
Envía mensaje de bienvenida |
/agente [prompt] |
Envía a n8n para IA |
!ping |
Responde "pong!" |
Modos de Chat:
agent: Menú de selección (bot/IA)bot: Comandos normalesia: Todo se envía a n8n
Traducción:
- Detecta idioma automáticamente
- Encola traducciones para todos los idiomas activos
- Botones para traducir manualmente
7.2 Bot de Telegram (telegram_bot_webhook.php)
Tecnologías:
- API de Webhooks de Telegram
- cURL para llamadas HTTP
Flujo de un mensaje:
1. Telegram envía Update al webhook
└── Autenticación por auth_token
2. Determina tipo de chat:
├── Chat privado → Modo agente/IA
│ ├── Registro de nuevo usuario
│ ├── Menú de bienvenida
│ └── Modos: agent, bot, ia
│
└── Grupo/Canal → Lógica de bot
├── Nuevos miembros → Se registran
├── Comandos (/) → Se procesan
├── #comando → Envía plantilla
└── Mensajes normales → Traducción
3. Comandos disponibles:
├── /setlang XX - Idioma
├── /bienvenida - Mensaje de bienvenida
├── /comandos - Lista de comandos
└── /agente - Cambiar a modo IA
4. Traducción:
├── Automática en cola
└── Botones inline para traducir
### 7.3 Registro de Usuarios y Mensajes de Bienvenida
#### Discord - Registro de Nuevos Miembros
Cuando un nuevo miembro se une al servidor de Discord, el bot ejecuta el evento `GUILD_MEMBER_ADD`:
Evento: GUILD_MEMBER_ADD └── Se ejecuta en: discord_bot.php (líneas 53-66) │ ├── 1. Obtiene datos del miembro: │ ├── platform_id = member.id (ID de Discord) │ ├── name = member.user.username │ └── platform = 'discord' │ ├── 2. Inserta/actualiza en tabla 'recipients': │ └── INSERT INTO recipients (platform_id, name, type, platform, language_code) │ VALUES (?, ?, 'user', 'discord', 'es') │ ON DUPLICATE KEY UPDATE name = VALUES(name) │ └── 3. Queda registrado para recibir mensajes
**Ubicación en código:** `discord_bot.php:53-66`
#### Telegram - Registro de Nuevos Usuarios
Cuando un usuario interactúa por primera vez con el bot de Telegram:
Evento: Primer mensaje / interacción └── Se ejecuta en: telegram_bot_webhook.php (líneas 99-142) │ ├── 1. Verifica configuración de registro: │ └── SELECT * FROM telegram_bot_messages WHERE id = 1 │ └── register_users = 1 (habilitado por defecto) │ ├── 2. Obtiene datos del usuario: │ ├── platform_id = from.id │ ├── name = first_name + last_name │ ├── language_code = from.language_code │ └── platform = 'telegram' │ ├── 3. Inserta en tabla 'recipients': │ └── INSERT INTO recipients (platform_id, name, type, platform, language_code, chat_mode) │ VALUES (?, ?, 'user', 'telegram', ?, 'agent') │ ON DUPLICATE KEY UPDATE name = VALUES(name) │ └── 4. Si está activo, envía mensaje de bienvenida: ├── Lee configuración: telegram_bot_messages ├── Reemplaza {user_name} con el nombre del usuario ├── Envía botón con enlace al grupo └── Registra interacción en telegram_bot_interactions
**Ubicación en código:** `telegram_bot_webhook.php:99-142`
#### Telegram - Nuevos Miembros en Grupos
Cuando un nuevo miembro se une a un grupo de Telegram:
Evento: new_chat_members (en grupos) └── Se ejecuta en: telegram_bot_webhook.php (líneas 222-234) │ ├── 1. Detecta nuevos miembros: │ └── message['new_chat_members'] │ ├── 2. Para cada nuevo miembro (si no es bot): │ ├── Registra en recipients │ └── Language code del usuario │ └── 3. No envía bienvenida automática (solo en chat privado)
**Ubicación en código:** `telegram_bot_webhook.php:222-234`
#### Mensaje de Bienvenida - Configuración
Los mensajes de bienvenida se configuran desde el panel de admin:
**Para Telegram:**
- **Ubicación**: `telegram/admin/telegram_bot_interactions.php`
- **Tabla**: `telegram_bot_messages`
- **Campos configurables**:
- `message_text`: Texto del mensaje (soporta `{user_name}`)
- `button_text`: Texto del botón de invitación
- `group_invite_link`: Enlace al grupo de Telegram
- `is_active`: Habilitar/deshabilitar mensaje
- `register_users`: Registrar automáticamente usuarios
**Ejemplo de mensaje de bienvenida:**
¡Hola {user_name}! 👋
Puedes usar /comandos para obtener una lista de comandos con la información que tenemos sobre el juego y solicitarla con el #comando.
También puedes usar /agente, para interactuar con los comandos o con la AI que tenemos.
Gracias por interactuar con nuestro bot de REOD. Únete a nuestro grupo principal para mantenerte actualizado.
**Tabla de Interacciones:**
- Los usuarios quedan registrados en `telegram_bot_interactions`
- Tipos de interacción: 'message', 'start', 'callback', etc.
- Permite hacer auditoría de uso del bot
---
## 8. Páginas Principales y sus Archivos
### index.php (Dashboard)
- **Propósito**: Mostrar mensajes programados del usuario
- **Archivos incluidos**:
- `includes/session_check.php`
- `includes/db.php`
- `templates/header.php`
- `templates/footer.php`
- **Datos**: Query de `schedules` + `messages` + `recipients`
### create_message.php (Crear Mensaje)
- **Propósito**: Formulario para crear nuevo mensaje
- **Archivos incluidos**:
- `includes/session_check.php`
- `includes/db.php`
- `templates/header.php`
- `templates/footer.php`
- **Funcionalidades**:
- Carga plantillas de `recurrent_messages`
- Editor Summernote
- Galería de imágenes (modal)
- Selección de plataforma/destinatario
- Programación (ahora/fecha/recurrente)
### scheduled_messages.php
- **Propósito**: Lista de mensajes programados
- **Procesa**: Tabla `schedules` con JOINs
### recurrentes.php (Plantillas)
- **Propósito**: Gestionar plantillas de mensajes
- **Archivos incluidos**:
- `includes/recurrent_message_handler.php`
- **Funcionalidades**:
- CRUD de plantillas
- Comando Telegram asociado
- Preview de contenido
### gallery.php
- **Propósito**: Gestión de imágenes
- **Archivos**: `upload.php`, `delete_image.php`, `rename_image.php`
- **Carpeta**: `/galeria/`
### admin/users.php
- **Propósito**: Gestión de usuarios del sistema
- **Acceso**: Solo admins (`role = 'admin'`)
- **Funcionalidades**:
- Crear/editar usuarios
- Asignar roles
- Vincular Telegram
### admin/recipients.php
- **Propósito**: Gestión de destinatarios
- **Plataformas**: Discord + Telegram
- **Tipos**: Canales + Usuarios
### admin/languages.php
- **Propósito**: Configurar idiomas de traducción
- **Proveedor**: LibreTranslate
- **Funcionalidades**:
- Activar/desactivar idiomas
- Editar emoji de bandera
- Sincronización con API
### telegram/admin/telegram_bot_interactions.php
- **Propósito**: Configurar mensaje de bienvenida de Telegram
- **Tabla**: `telegram_bot_messages`
- **Funcionalidades**:
- Editar mensaje de bienvenida
- Configurar botón de invitación
- Establecer enlace al grupo
- Activar/desactivar registro automático de usuarios
### telegram/admin/telegram_welcome.php
- **Propósito**: Configurar mensajes de bienvenida por grupo
- **Tabla**: `telegram_welcome_messages`
- **Funcionalidades**:
- Configurar mensaje por cada grupo
- Personalizar botón e invitación
### telegram/admin/chat_telegram.php
- **Propósito**: Ver historial de interacciones con el bot
- **Tabla**: `telegram_bot_interactions`
- **Funcionalidades**:
- Lista de usuarios que han interactuado
- Tipo de interacción (message, start, etc.)
- Fecha de última interacción
### admin/activity.php
- **Propósito**: Ver registro de actividades del sistema
- **Tabla**: `activity_log`
- **Acciones registradas**:
- Inicio/cierre de sesión
- Creación de mensajes
- Eliminación de mensajes
- Actualizaciones de usuarios
- Eliminación de imágenes
---
## 9. Variables de Entorno (.env)
```env
# Entorno
APP_ENVIRONMENT=pruebas # o 'reod' para producción
# Base de datos
DB_HOST=10.10.4.17
DB_PORT=3390
DB_NAME=bot
DB_USER=root
DB_PASS=*****
# Discord
DISCORD_BOT_TOKEN=*****
DISCORD_GUILD_ID=*****
DISCORD_CLIENT_ID=*****
DISCORD_CLIENT_SECRET=*****
# Telegram
TELEGRAM_BOT_TOKEN=*****
TELEGRAM_WEBHOOK_TOKEN=*****
# Traducción
LIBRETRANSLATE_URL=http://libretranslate:5000
# n8n (Automatización/IA)
N8N_URL=*****
N8N_TOKEN=*****
N8N_IA_WEBHOOK_URL=*****
N8N_IA_WEBHOOK_URL_DISCORD=*****
N8N_PROCESS_QUEUE_WEBHOOK_URL=*****
# Seguridad
JWT_SECRET=*****
APP_URL=https://tu-dominio.com
# API Interna
INTERNAL_API_KEY=*****
10. Configuración de Producción
Cron Jobs Recomendados
# Procesar cola de mensajes cada minuto
* * * * * /usr/bin/php /var/www/html/bot/process_queue.php
# Limpiar logs antiguos (semanalmente)
0 0 * * 0 find /var/www/html/bot/logs -name "*.log" -mtime +30 -delete
# Reiniciar bots si fallan (cada 5 minutos)
*/5 * * * * pgrep -f "discord_bot.php" || /usr/bin/php /var/www/html/bot/discord_bot.php >> /var/www/html/bot/logs/discord_bot.out.log 2>&1 &
Webhooks
# Telegram Webhook
https://tu-dominio.com/telegram_bot_webhook.php?auth_token=TOKEN
# n8n (procesamiento)
URL configurable desde admin
11. Funcionalidades por Archivo
| Archivo | Función Principal |
|---|---|
discord_bot.php |
Bot de Discord en tiempo real |
telegram_bot_webhook.php |
Recibe mensajes de Telegram |
process_queue.php |
Procesa mensajes programados |
includes/message_handler.php |
Maneja creación/edición de mensajes |
src/Translate.php |
Wrapper para LibreTranslate |
discord/DiscordSender.php |
Envía mensajes a Discord |
telegram/TelegramSender.php |
Envía mensajes a Telegram |
common/helpers/converter_factory.php |
Convierte HTML entre formatos |
12. Resumen de Flujos
Flujo Completo de un Mensaje Programado
Usuario → create_message.php → message_handler.php
→ schedules (DB) → process_queue.php (cron)
→ DiscordSender/TelegramSender → API Plataforma
→ sent_messages (DB) → (si recurrente) → recalcular próximo
Flujo de Traducción
Mensaje con data-translate="true"
→ translation_queue (DB)
→ TranslationWorker
→ LibreTranslate
→ Envío a usuario
Flujo de Bot (Discord/Telegram)
Plataforma → Webhook/Bot Event
→ Verificar usuario
→ Procesar comando/traducción
→ Responder
→ Actualizar DB
13. Conclusiones
El sistema está bien estructurado y cumple con los siguientes objetivos:
- Multiplataforma: Soporta Discord y Telegram desde una sola interfaz
- Flexible: Permite programación simple o recurrente
- Traducible: Integración con LibreTranslate para automático y manual
- Escalable: Uso de colas y workers para procesamiento asíncrono
- Administrable: Panel completo para gestión de usuarios, destinatarios e idiomas
- Integrado: Conexión con n8n para automatización avanzada e IA
El código utiliza patrones modernos de PHP (PDO, Composer, Namespaces) y sigue una estructura modular que facilita el mantenimiento y expansión futura.