Telegram Bot Project

Descripción

Bot de Telegram multilingüe en Python con modos de conversación interactiva. Incluye sistema completo de internacionalización con soporte para español, inglés, francés y alemán. Permite activar conversaciones con DialogFlow CX o n8n con IA, con timeout automático de 2 minutos para mantener la eficiencia.

Funcionalidades Principales

• ✅ Sistema Multilingüe: Detección automática de idioma basada en configuración de Telegram
• ✅ Modos de Conversación: Activación de modos DialogFlow o n8n con IA mediante botones
• ✅ Timeout Automático: Cierre automático de conversaciones después de 2 minutos de inactividad
• ✅ Flujo Continuo: Después de cada acción, se muestra automáticamente el menú principal
• ✅ Integración Dialogflow: Procesamiento inteligente de conversaciones en modo dedicado
• ✅ Integración n8n: Respuestas con IA en modo dedicado
• ✅ Historial Limpio: Mantiene el menú original visible y agrega resultados como mensajes separados

Estructura del Proyecto

telegram-bot/
├── src/
│   ├── __init__.py
│   ├── bot.py              # Código principal del bot (modo polling para desarrollo local)
│   ├── webhook.py          # Servidor FastAPI para webhooks (modo producción)
│   ├── handlers.py         # Handlers para mensajes y botones
│   ├── config.py           # Configuraciones (tokens, etc.)
│   ├── translations.py     # Sistema de internacionalización
│   └── integrations/       # Módulos para integraciones
│       ├── __init__.py
│       ├── dialogflow.py   # Integración con Dialogflow CX
│       └── n8n.py          # Integración con n8n
├── config/
│   └── settings.json       # Configuraciones JSON
├── tests/
│   ├── __init__.py
│   └── test_bot.py         # Pruebas unitarias
├── requirements.txt        # Dependencias
├── dockerfile              # Dockerfile para contenedorización
├── .dockerignore           # Archivos a ignorar en Docker
├── .env                    # Variables de entorno (token del bot)
├── .env.example            # Ejemplo de variables de entorno
├── .gitignore              # Archivos ignorados por Git
├── setup-dialogflow-gcloud.ps1  # Script para configurar Dialogflow en Google Cloud
├── verify-dialogflow-gcloud.ps1 # Script para verificar configuración de Dialogflow
├── dialogflow-key-*.json   # Claves de servicio de Dialogflow (no subir a Git)
├── workupbots-*.json       # Claves adicionales de Dialogflow
├── .dist/                  # Directorio de distribución/build
└── README.md               # Este archivo

Arquitectura del Código

• bot.py: Inicializa el bot en modo polling para desarrollo local y registra handlers.
• webhook.py: Servidor FastAPI que maneja webhooks de Telegram para despliegue en producción.
• handlers.py: Maneja mensajes de texto y callbacks de botones con soporte multilingüe.
• translations.py: Sistema completo de internacionalización con diccionarios de traducciones.
• config.py: Carga configuraciones desde archivos JSON y variables de entorno.
• integrations/: Módulos modulares para Dialogflow (procesamiento de conversaciones) y n8n (ejecución de flujos y llamadas a APIs), ambos con soporte i18n.

Diagrama de Flujo

graph TD
    A{¿Modo de ejecución?}
    A -->|Polling (Desarrollo)| B[Iniciar bot.py con polling]
    A -->|Webhook (Producción)| C[Iniciar webhook.py con FastAPI]

    B --> D[Usuario envía /start]
    C --> D

    D --> E[Detectar idioma del usuario]
    E --> F[Enviar menú principal localizado]
    F --> G[Usuario presiona botón]

    G --> H{¿Botón seleccionado?}
    H -->|Iniciar Conversación con DialogFlow| I[Activar modo DialogFlow]
    H -->|Responde n8n, con IA| J[Activar modo n8n con IA]
    H -->|Ayuda| K[Mostrar ayuda y menú]

    I --> L[Enviar mensaje de activación]
    L --> M[Esperar mensajes del usuario]
    M --> N[Procesar con DialogFlow]
    N --> O[Enviar respuesta]
    O --> P{¿Timeout 2 min?}
    P -->|No| M
    P -->|Sí| Q[Enviar mensaje timeout y resetear]

    J --> R[Enviar mensaje de activación]
    R --> S[Esperar mensajes del usuario]
    S --> T[Procesar con n8n IA]
    T --> U[Enviar respuesta]
    U --> V{¿Timeout 2 min?}
    V -->|No| S
    V -->|Sí| W[Enviar mensaje timeout y resetear]

    Q --> F
    W --> F
    K --> F

    X[Detectar idioma] --> Y[Seleccionar traducciones apropiadas]
    Y --> F
    Y --> L
    Y --> R
    Y --> O
    Y --> U
    Y --> Q
    Y --> W

    Z[Sistema de Traducciones] --> AA[Soporte: ES, EN, FR, DE]
    AA --> Y

Loading

Sistema Multilingüe (i18n)

Idiomas Soportados

• 🇪🇸 Español (predeterminado)
• 🇺🇸 Inglés
• 🇫🇷 Francés
• 🇩🇪 Alemán

Detección de Idioma

El bot detecta automáticamente el idioma del usuario basado en la configuración de Telegram:

• Lee update.effective_user.language_code
• Soporta códigos como: es, en, fr, de y sus variantes (es-ES, en-US, etc.)
• Si no reconoce el código, usa español como predeterminado

Configuración de Idioma

Para cambiar el idioma:

1. En Telegram: Configuración → Idioma → Seleccionar idioma
2. Reiniciar el bot con /start

Para forzar un idioma específico:

# En src/translations.py
DEFAULT_LANGUAGE = 'en'  # Cambiar a 'es', 'fr', 'de' según necesites

Integraciones

Dialogflow CX

• ✅ Implementado: Procesamiento inteligente de conversaciones
• ✅ Multilingüe: Respuestas localizadas según idioma del usuario
• Ubicación: integrations/dialogflow.py

n8n

• ✅ Implementado: Ejecución de flujos de trabajo
• ✅ Multilingüe: Resultados localizados
• Ubicación: integrations/n8n.py

Dependencias

• ✅ python-telegram-bot[job-queue]: Para interactuar con la API de Telegram y manejo de jobs
• ✅ requests: Para llamadas HTTP a integraciones
• ✅ python-dotenv: Para manejar variables de entorno
• ✅ fastapi: Framework web para el servidor de webhooks
• ✅ uvicorn: Servidor ASGI para FastAPI
• ✅ google-cloud-dialogflow-cx: Cliente para Dialogflow CX

Instalación y Configuración

1. Instalar dependencias

pip install -r requirements.txt

2. Configurar variables de entorno

cp .env.example .env
# Editar .env con tus tokens y configuraciones

3. Configurar integraciones (opcional)

• Para Dialogflow: Ejecutar setup-dialogflow-gcloud.ps1 y verify-dialogflow-gcloud.ps1 en PowerShell.
• Habilitar integraciones en config/settings.json cambiando "enabled": true.

4. Ejecutar el bot

Modo Desarrollo (Polling)

# Asegurarse de que ENV=LOCAL en .env
python -m src.bot

Modo Producción (Webhook)

# Configurar BASE_URL en .env (ej: https://tu-dominio.com)
python -m src.webhook
# O con uvicorn: uvicorn src.webhook:app --host 0.0.0.0 --port 8000

Con Docker

docker build -t telegram-bot .
docker run -p 8000:8000 --env-file .env telegram-bot

Despliegue en Producción

Google Cloud Run

1. Construir y subir imagen a GCR:

gcloud builds submit --tag gcr.io/PROJECT-ID/telegram-bot

2. Desplegar en Cloud Run:

gcloud run deploy telegram-bot \
  --image gcr.io/PROJECT-ID/telegram-bot \
  --platform managed \
  --allow-unauthenticated \
  --set-env-vars ENV=PROD,BASE_URL=https://tu-servicio.run.app

3. Configurar webhook en Telegram apuntando a la URL de Cloud Run.

Otras Plataformas

El contenedor puede desplegarse en cualquier servicio que soporte contenedores (AWS ECS, Heroku, etc.), asegurando que BASE_URL esté configurada correctamente.

Ejemplos de Uso

Flujo en Español

Usuario: /start
Bot: ¡Hola! Soy tu bot. Elige una opción: [Iniciar Conversación con DialogFlow] [Responde n8n, con IA] [Ayuda]

Usuario: [Click en Iniciar Conversación con DialogFlow]
Bot: A partir de ahora responderá DialogFlow
Usuario: Hola, ¿cómo estás?
Bot: Respuesta de Dialogflow para: Hola, ¿cómo estás?
Usuario: [Después de 2 min sin respuesta]
Bot: Por cuestiones de tiempo, hemos de terminar la conversación
Bot: ¡Hola! Soy tu bot. Elige una opción: [Iniciar Conversación con DialogFlow] [Responde n8n, con IA] [Ayuda]

Flujo en Inglés

Usuario: /start
Bot: Hello! I am your bot. Choose an option: [Start Conversation with DialogFlow] [Respond n8n, with AI] [Help]

Usuario: [Click en Start Conversation with DialogFlow]
Bot: From now on, DialogFlow will respond
Usuario: Hello, how are you?
Bot: Dialogflow response for: Hello, how are you?
Usuario: [Después de 2 min sin respuesta]
Bot: Due to time constraints, we must end the conversation
Bot: Hello! I am your bot. Choose an option: [Start Conversation with DialogFlow] [Respond n8n, with AI] [Help]

Estado del Proyecto

• ✅ Código básico del bot: Implementado y funcional
• ✅ Sistema multilingüe: Completamente implementado
• ✅ Integración Dialogflow: Implementada con soporte i18n
• ✅ Integración n8n: Implementada con soporte i18n
• ✅ Flujo de continuidad: Implementado
• ✅ Modo webhook para producción: Implementado con FastAPI
• ✅ Contenedorización con Docker: Dockerfile y configuración lista
• ✅ Scripts de configuración para Dialogflow: Setup y verificación en PowerShell
• ✅ Pruebas básicas: Implementadas (placeholders para expansión)
• ✅ Configuración modular: settings.json para habilitar/deshabilitar integraciones

Próximos Pasos

1. ✅ Implementado: Sistema multilingüe completo
2. ✅ Implementado: Integraciones Dialogflow y n8n
3. ✅ Implementado: Modo webhook y Docker
4. 🔄 En progreso: Expandir pruebas unitarias (actualmente placeholders)
5. 🔄 Pendiente: Agregar logging avanzado con rotación de logs
6. 🔄 Pendiente: Implementar manejo de errores robusto y recuperación automática
7. 🔄 Pendiente: Agregar métricas y monitoreo (health checks ya implementado)
8. 🔄 Pendiente: Optimizar rendimiento y escalabilidad