BOT DE SORTEOS PARA WHATSAPP

Descripción completa

Este proyecto consiste en un bot automatizado para WhatsApp diseñado para facilitar la gestión de sorteos y concursos de manera digital, asignando números únicos aleatorios a cada participante que escribe una palabra clave específica.

El sistema está desarrollado con Node.js y TypeScript, utilizando la librería whatsapp-web.js para la integración con WhatsApp. Implementa una base de datos SQLite para garantizar la persistencia de datos y evitar duplicados, asegurando que cada número de teléfono pueda participar una sola vez por sorteo.

La solución incorpora sistema anti-spam, delays configurables entre mensajes, validación de palabras clave y un robusto sistema de logging con Pino para monitoreo en tiempo real. El bot está completamente dockerizado, facilitando su despliegue en cualquier entorno de producción.

Este proyecto demuestra el uso práctico de automatización de mensajería, gestión de bases de datos, arquitectura limpia con separación de responsabilidades y buenas prácticas de desarrollo aplicables en contextos tanto personales como empresariales para gestión de eventos, rifas promocionales o concursos comunitarios.

Características principales

• Registro automático de participantes
  Detección automática de palabra clave configurable para iniciar el proceso de participación.

• Asignación de números únicos aleatorios
  Generación de números del 1 al 100 sin repetición por sorteo activo.

• Validación de participación única
  Cada número de teléfono puede participar solo una vez, evitando duplicados.

• Persistencia de datos con SQLite
  Base de datos relacional ligera para almacenar participantes y números asignados.

• Sistema anti-spam integrado
  Protección contra abuso mediante control de frecuencia de mensajes por usuario.

• Delays configurables
  Gestión de tiempos de espera entre respuestas para evitar bloqueos de WhatsApp.

• Sistema de logging robusto
  Monitoreo en tiempo real de eventos, errores y actividad del bot con Pino.

• Arquitectura modular y escalable
  Código organizado en servicios, handlers y utilidades para fácil mantenimiento.

• Exportación de datos
  Capacidad para exportar participantes a formato CSV para análisis posterior.

• Normalización de texto
  Procesamiento inteligente de palabras clave ignorando acentos y mayúsculas.

• Despliegue con Docker
  Containerización completa con Docker Compose para instalación rápida y portable.

• Variables de entorno configurables
  Personalización de palabra clave, enlaces y parámetros sin modificar código.

• Soporte de sesión persistente
  Mantenimiento de sesión de WhatsApp entre reinicios del contenedor.

• Gestión de errores centralizada
  Manejo robusto de excepciones para garantizar estabilidad del servicio.

Arquitectura del proyecto

bot_sorteo/
├── src/
│   ├── handlers/          # Manejadores de mensajes
│   ├── services/          # Lógica de negocio
│   │   ├── antiSpamService.ts
│   │   ├── participationService.ts
│   │   ├── raffleService.ts
│   │   └── keywordService.ts
│   ├── utils/             # Utilidades compartidas
│   └── index.ts           # Punto de entrada
├── db/                    # Base de datos SQLite
├── data/session/          # Sesión de WhatsApp persistente
├── docker/                # Configuración Docker
└── docker-compose.yml     # Orquestación de contenedores

Casos de uso

• Rifas empresariales: Sorteos promocionales en campañas de marketing
• Concursos comunitarios: Gestión de participantes en eventos sociales
• Sorteos en grupos: Asignación aleatoria de premios o turnos
• Eventos corporativos: Distribución de códigos o accesos
• Dinámicas de engagement: Activación de audiencia en comunidades digitales