erp-core/docs/04-modelado/requerimientos-funcionales/mgn-017

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	Conexión WhatsApp Business API	P1	13	Definido
RF-MGN-017-002	Gestión de Templates de Mensajes	P1	8	Definido
RF-MGN-017-003	Envío de Notificaciones Transaccionales	P1	8	Definido
RF-MGN-017-004	Inbox de Conversaciones	P1	13	Definido
RF-MGN-017-005	Chatbot Automatizado (Flujos)	P2	13	Definido
RF-MGN-017-006	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

-- 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

{
  "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

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>;
  };
}