# MGN-017: WhatsApp Business Integration

## Descripción del Módulo

El módulo de WhatsApp Business Integration permite a los tenants conectar una o más cuentas de WhatsApp Business para automatizar la comunicación con sus clientes. Incluye envío de notificaciones, mensajes de marketing, chatbots automatizados, y integración con agentes de IA.

## Requerimientos Funcionales

| ID | Nombre | Prioridad | Story Points | Estado |
|----|--------|-----------|--------------|--------|
| [RF-MGN-017-001](./RF-MGN-017-001-conexion-whatsapp-business.md) | Conexión WhatsApp Business API | P1 | 13 | Definido |
| [RF-MGN-017-002](./RF-MGN-017-002-templates-mensajes.md) | Gestión de Templates de Mensajes | P1 | 8 | Definido |
| [RF-MGN-017-003](./RF-MGN-017-003-envio-notificaciones.md) | Envío de Notificaciones Transaccionales | P1 | 8 | Definido |
| [RF-MGN-017-004](./RF-MGN-017-004-inbox-conversaciones.md) | Inbox de Conversaciones | P1 | 13 | Definido |
| [RF-MGN-017-005](./RF-MGN-017-005-chatbot-automatizado.md) | Chatbot Automatizado (Flujos) | P2 | 13 | Definido |
| [RF-MGN-017-006](./RF-MGN-017-006-integracion-crm.md) | Integración con CRM | P2 | 8 | Definido |

**Total Story Points:** 63

## Arquitectura

```
┌──────────────────────────────────────────────────────────────────┐
│                         TENANT                                    │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐          │
│  │  WhatsApp   │    │   Message   │    │   Chatbot   │          │
│  │  Account    │    │  Templates  │    │    Flows    │          │
│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘          │
│         │                  │                   │                  │
└─────────┼──────────────────┼───────────────────┼──────────────────┘
          │                  │                   │
          ▼                  ▼                   ▼
┌─────────────────────────────────────────────────────────────────┐
│                    WhatsApp Business API                         │
│                    (Cloud API via Meta)                          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Cliente Final                               │
│                    (WhatsApp Personal)                           │
└─────────────────────────────────────────────────────────────────┘
```

## Dependencias

### Dependencias Internas
- **MGN-003 (Catalogs):** Contactos con número de WhatsApp (requiere campo `whatsapp_number`)
- **MGN-007 (Sales):** Notificaciones de pedidos (confirmación, envío, entrega)
- **MGN-009 (CRM):** Leads y oportunidades desde WhatsApp (auto-crear leads)
- **MGN-014 (Mensajería):** Auditoría de mensajes y notificaciones internas
- **MGN-015 (Billing):** Feature flags (whatsapp_enabled, whatsapp_chatbot, whatsapp_marketing)

### Dependencias Opcionales
- **MGN-018 (AI Agents):** Para RF-005 (Chatbot con IA) - No requerido para RF-001 a RF-004

### Dependencias Externas
- Meta Business Suite
- WhatsApp Business API (Cloud API)
- Proveedor BSP opcional (Twilio, MessageBird, 360dialog)

### Integraciones Requeridas
- **MGN-003:** Agregar campo `whatsapp_number` y `whatsapp_opt_in` a contactos
- **MGN-009:** Crear leads automáticamente desde conversaciones nuevas
- **MGN-007:** Templates para confirmación de pedido, actualización de envío

### Nota sobre Interdependencia con MGN-018
RF-005 (Chatbot Automatizado) puede funcionar en dos modos:
1. **Flujos simples:** Sin MGN-018, usa reglas y condiciones predefinidas
2. **Flujos con IA:** Con MGN-018, usa AI Agents para respuestas inteligentes

Esta separación evita dependencia circular. MGN-017 es la capa de transporte, MGN-018 es la capa de inteligencia.

## Actores del Módulo

| Actor | Descripción | RFs Relacionados |
|-------|-------------|------------------|
| Tenant Admin | Configura integración y templates | RF-001, RF-002 |
| Agente de Ventas | Atiende conversaciones | RF-004 |
| Sistema | Envía notificaciones automáticas | RF-003 |
| Chatbot | Responde automáticamente | RF-005 |
| Cliente | Recibe/envía mensajes | Todos |

## Entidades Principales

```sql
-- Schema: messaging
messaging.whatsapp_accounts          -- Cuentas conectadas por tenant
messaging.whatsapp_templates         -- Templates aprobados por Meta
messaging.whatsapp_conversations     -- Conversaciones activas
messaging.whatsapp_messages          -- Mensajes enviados/recibidos
messaging.chatbot_flows              -- Flujos de chatbot
messaging.chatbot_nodes              -- Nodos de cada flujo
messaging.chatbot_sessions           -- Sesiones activas de chatbot
```

## Tipos de Mensajes WhatsApp

### 1. Mensajes de Template (Outbound)
- Requieren aprobación de Meta
- Usados para iniciar conversaciones
- Categorías: Marketing, Utility, Authentication

### 2. Mensajes de Sesión (Bidireccional)
- Ventana de 24 horas después de que cliente escriba
- Mensajes libres (texto, imagen, documento)
- Sin costo adicional por mensaje

### 3. Mensajes de Respuesta Rápida
- Dentro de ventana de 24 horas
- Respuestas del agente o chatbot

## Pricing de WhatsApp Business API

### Conversaciones (Modelo Meta 2024)

| Categoría | Descripción | Costo Aprox (MX) |
|-----------|-------------|------------------|
| Marketing | Promociones, ofertas | $0.80 MXN |
| Utility | Confirmaciones, actualizaciones | $0.40 MXN |
| Authentication | OTPs, verificación | $0.35 MXN |
| Service | Iniciadas por cliente | $0.30 MXN |

*Primeras 1,000 conversaciones de servicio gratis/mes*

## Casos de Uso Principales

### 1. Notificaciones Transaccionales
```
[Confirmación de Pedido]
Hola {{nombre}}, tu pedido #{{numero}} ha sido confirmado.
Total: ${{total}}
Entrega estimada: {{fecha}}
```

### 2. Recuperación de Carritos
```
[Carrito Abandonado]
¡Hola {{nombre}}! Vimos que dejaste productos en tu carrito.
Completa tu compra con 10% de descuento usando el código: VUELVE10
```

### 3. Soporte al Cliente
```
Cliente: "¿Cuál es el estado de mi pedido?"
Chatbot: "Tu pedido #12345 está en camino. Llegará el 15 de enero."
```

## Flujo de Conexión

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Tenant    │────▶│    Meta     │────▶│  WhatsApp   │
│   Admin     │     │  Business   │     │  Business   │
└─────────────┘     │   Suite     │     │   Account   │
                    └─────────────┘     └─────────────┘
                          │
                          ▼
                    ┌─────────────┐
                    │   Obtener   │
                    │   Access    │
                    │   Token     │
                    └─────────────┘
                          │
                          ▼
                    ┌─────────────┐
                    │  Configurar │
                    │  Webhooks   │
                    └─────────────┘
```

## Seguridad

1. **Access Tokens:** Encriptados, rotación regular
2. **Webhooks:** Validación de firma de Meta
3. **Rate Limiting:** Respeto de límites de API
4. **Opt-in:** Solo enviar a usuarios con consentimiento
5. **GDPR/LFPDPPP:** Cumplimiento de privacidad

## Feature Flags

```json
{
  "whatsapp_enabled": true,
  "whatsapp_chatbot": true,
  "whatsapp_ai_agent": false,
  "whatsapp_marketing": true,
  "whatsapp_max_accounts": 3
}
```

## Notas de Implementación

1. **BSP vs Cloud API:** Se recomienda Cloud API directo para mejor control
2. **Número de Teléfono:** Debe ser número dedicado (no personal)
3. **Verificación:** Proceso de verificación de negocio con Meta
4. **Templates:** Tiempo de aprobación 24-48 horas
5. **Límites:** Inicialmente 250 conversaciones/día, escalable

## Métricas Clave

```typescript
interface WhatsAppMetrics {
  conversations: {
    total: number;
    byCategory: Record<string, number>;
  };
  messages: {
    sent: number;
    delivered: number;
    read: number;
    failed: number;
  };
  chatbot: {
    sessions: number;
    handoffs: number; // Escalados a agente
    resolutionRate: number;
  };
  costs: {
    current_month: number;
    by_category: Record<string, number>;
  };
}
```