# Cola de Envío de Mensajes – Documento Técnico

## 1. Descripción General

La cola de envío de mensajes es un mecanismo que permite **desacoplar la generación de mensajes de su envío**, controlando el ritmo, horario y volumen de entrega según configuraciones definidas por canal.

Este enfoque evita envíos masivos simultáneos, mejora la estabilidad del sistema y permite cumplir políticas de mensajería (por ejemplo, WhatsApp).

---

## 2. Flujo de Procesamiento

### 2.1 Flujo principal

1. **Generación del mensaje**
   - Una herramienta (ej. CRM, agenda, automatización) genera un mensaje.
   - Casos comunes:
     - Prospecto interesado en productos
     - Confirmación de cita
     - Recordatorios de reunión
     - Notificaciones operativas

2. **Invocación del servicio de envío**
   - Se consume el servicio:
     https://docs.induxsoft.net/es/iae/agentes/servicio-web-send.md
   - Se envía el parámetro:
     ```json
     {
       "queue": true
     }
     ```
   - Esto indica que el mensaje **NO se envía inmediatamente**.

3. **Encolado del mensaje**
   - El servicio registra el mensaje en la **cola de envíos**.
   - El mensaje queda pendiente de procesamiento.

4. **Procesador de cola**
   - Un proceso independiente revisa la cola.
   - Aplica la configuración del agente (según canal).
   - Determina:
     - Cuándo enviar
     - Si puede enviarse
     - Cuánto esperar

5. **Envío del mensaje**
   - Se envía respetando:
     - Retrasos
     - Límites diarios
     - Horarios
     - Días habilitados

---

## 3. Configuración por Canal

Cada canal tiene su propia configuración independiente:

- WhatsApp QR
- WhatsApp API

Si un canal **no tiene configuración definida**, se utiliza una configuración **predeterminada**.

---

## 4. Parámetros de Configuración

### 4.1 Tipo de retraso

Define cómo se calcula el tiempo entre envíos:

- **Fijo**
  - Se usa un tiempo constante entre mensajes.
  - Activa el campo:
    - `Esperar`

- **Variable**
  - Se usa un rango aleatorio de tiempo.
  - Activa el campo:
    - `Entre`

---

### 4.2 Esperar (solo modo fijo)

- Tiempo en segundos entre cada envío.

Ejemplo:

Esperar: 5 segundos


---

### 4.3 Entre (solo modo variable)

- Rango de tiempo en segundos.
- El sistema selecciona un valor aleatorio dentro del rango.

Ejemplo:

Entre: 10 y 180 segundos


---

### 4.4 Límite por día

- Cantidad máxima de mensajes enviados por día.
- Aplica únicamente a mensajes en cola.

Ejemplo:
Límite: 10 mensajes diarios

---

### 4.5 Horario de envío

- Rango de horas en las que se permite el envío.

Ejemplo:
De: 08:00:00
Hasta: 20:00:00


- Si el mensaje está fuera del horario:
  - Permanece en cola
  - Se envía cuando entre en horario válido

---

### 4.6 Días habilitados

- Define los días en los que se pueden enviar mensajes.

Ejemplo:
- Lunes 
- Martes 
- Miércoles 
- Jueves 
- Viernes 


- Comportamiento:
  - Si el día está habilitado -> se procesan mensajes
  - Si no -> permanecen en cola

---

## 5. Configuración Predeterminada

### 5.1 WhatsApp QR

- Tipo de retraso: **Variable**
- Entre: **10 a 180 segundos**
- Horario: **08:00:00 a 20:00:00**
- Días:
  - Lunes a Viernes

---

### 5.2 WhatsApp API

- Tipo de retraso: **Fijo**
- Esperar: **5 segundos**
- Horario: **08:00:00 a 20:00:00**
- Días:
  - Lunes a Domingo

---

## 6. Reglas de Procesamiento

El sistema evalúa las siguientes condiciones antes de enviar un mensaje:

1. ¿Está dentro del **horario permitido**?
2. ¿El **día está habilitado**?
3. ¿No se ha superado el **límite diario**?
4. ¿Se ha cumplido el **tiempo de espera/retraso**?

Si todas se cumplen:  
-> El mensaje se envía  

Si alguna falla:  
-> El mensaje permanece en cola  

---

## 7. Beneficios del Uso de Cola

- Evita bloqueos por envíos masivos
- Controla la velocidad de envío
- Permite cumplimiento de políticas de mensajería
- Mejora la estabilidad del sistema
- Permite priorizar y escalar envíos

---

## 8. Consideraciones Técnicas

- La cola debe ser persistente (DB o sistema de colas)
- El procesador debe ser tolerante a fallos
- Se recomienda:
  - Logs de envío
  - Reintentos controlados
  - Monitoreo de cola