# EPICA: EPIC-MGN-018 - WhatsApp Business

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | EPIC-MGN-018 |
| **Nombre** | WhatsApp Business Cloud API |
| **Modulo** | whatsapp |
| **Fase** | Fase 4 - SaaS Platform |
| **Prioridad** | P3 |
| **Estado** | Backlog |
| **Story Points** | 42 |
| **Sprint(s)** | Sprint 23-25 |

---

## Descripcion

Integracion con WhatsApp Business Cloud API para comunicacion bidireccional con clientes. Incluye gestion de cuentas de WhatsApp Business por tenant, templates de mensajes (HSM) aprobados por Meta, conversaciones bidireccionales, chatbots con flujos visuales y campanas de marketing masivo.

---

## Objetivo de Negocio

Proveer integracion WhatsApp que:
- Permita comunicacion directa con clientes via WhatsApp
- Automatice respuestas con chatbots configurables
- Envie notificaciones proactivas (facturas, recordatorios)
- Gestione campanas de marketing masivo
- Centralice comunicaciones en el ERP

---

## Stakeholders

| Rol | Nombre/Equipo | Responsabilidad |
|-----|---------------|-----------------|
| Product Owner | Equipo Producto | Definicion de funcionalidades |
| Tech Lead | Equipo Backend | Arquitectura de mensajeria |
| Marketing | Comercial | Diseño de campanas |
| Soporte | Operaciones | Gestion de conversaciones |

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-MGN018-001 | Como admin, quiero conectar mi numero de WhatsApp Business | P0 | 5 | Backlog |
| US-MGN018-002 | Como sistema, quiero recibir mensajes via webhook | P0 | 5 | Backlog |
| US-MGN018-003 | Como sistema, quiero identificar contacto por telefono | P0 | 3 | Backlog |
| US-MGN018-004 | Como usuario, quiero enviar mensajes a clientes | P0 | 5 | Backlog |
| US-MGN018-005 | Como admin, quiero crear templates de mensajes | P0 | 5 | Backlog |
| US-MGN018-006 | Como admin, quiero crear flujos de chatbot visual | P1 | 8 | Backlog |
| US-MGN018-007 | Como marketing, quiero enviar campanas masivas | P1 | 5 | Backlog |
| US-MGN018-008 | Como usuario, quiero ver historial de conversaciones | P0 | 3 | Backlog |
| US-MGN018-009 | Como admin, quiero ver metricas de mensajes | P1 | 3 | Backlog |

**Total Story Points:** 42 SP

---

## Criterios de Aceptacion de la Epica

**Funcionales:**
- [ ] Configuracion de cuentas WhatsApp Business por tenant
- [ ] Recepcion de mensajes via Cloud API webhooks
- [ ] Envio de mensajes de texto, imagenes, documentos
- [ ] Templates de mensajes (HSM) con variables
- [ ] Chatbot con flujos configurables (sin codigo)
- [ ] Campanas masivas con opt-in/opt-out
- [ ] Historial de conversaciones con busqueda
- [ ] Metricas de entrega, lectura, respuesta

**No Funcionales:**
- [ ] Latencia de respuesta < 3s
- [ ] Cumplimiento de politicas de Meta (24h window)
- [ ] Rate limiting segun limites de Cloud API
- [ ] Retry automatico en fallos

**Tecnicos:**
- [ ] Cobertura de tests > 80%
- [ ] Webhook verification implementado
- [ ] Queue para mensajes salientes

---

## Tipos de Mensajes Soportados

| Tipo | Entrada | Salida |
|------|---------|--------|
| Texto | Si | Si |
| Imagen | Si | Si |
| Documento | Si | Si |
| Audio | Si | No |
| Video | Si | Si |
| Ubicacion | Si | Si |
| Template (HSM) | No | Si |
| Interactive (Botones) | Si | Si |
| Interactive (Lista) | No | Si |

---

## Dependencias

**Esta epica depende de:**
| Epica/Modulo | Estado | Bloqueante |
|--------------|--------|------------|
| EPIC-MGN-001 Auth | Ready | Si |
| EPIC-MGN-004 Tenants | Ready | Si |
| EPIC-MGN-005 Catalogs (Contacts) | Backlog | Si |
| EPIC-MGN-016 Billing (Feature Flag) | Backlog | Si |

**Esta epica bloquea:**
| Epica/Modulo | Razon |
|--------------|-------|
| EPIC-MGN-019 AI Agents | Canal de comunicacion |

---

## Desglose Tecnico

**Database:**
- [ ] Schema: `messaging`
- [ ] Tablas: 8 (whatsapp_accounts, templates, conversations, messages, chatbot_flows, chatbot_nodes, campaigns, opt_outs)
- [ ] Indices: Por phone_number, conversation_id, status
- [ ] RLS Policies: Si (por tenant)

**Backend:**
- [ ] Modulo: `whatsapp`
- [ ] Services: WhatsAppService, TemplateService, ChatbotEngine, CampaignService
- [ ] Controllers: WhatsAppController, WebhooksController, ConversationsController
- [ ] Endpoints: 25+ (enviar mensaje, templates, chatbot, campanas)
- [ ] Jobs: CampaignSenderJob, MessageRetryJob
- [ ] Tests: 35+

**Frontend:**
- [ ] Paginas: 6 (Conversations, Templates, ChatbotBuilder, Campaigns, Contacts, Analytics)
- [ ] Componentes: ChatWindow, MessageBubble, TemplateEditor, FlowCanvas, CampaignWizard
- [ ] Stores: 1 (whatsappStore)

---

## Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Numero baneado por Meta | Media | Critico | Cumplir politicas, opt-in obligatorio |
| Template rechazado | Alta | Medio | Guidelines claros, preview antes de enviar |
| Rate limiting excedido | Media | Medio | Queue con throttling |
| Costos de mensajes altos | Media | Medio | Monitoreo, limites por tenant |

---

## Estimacion de Costos (Meta)

| Tipo Mensaje | Costo (MXN) |
|--------------|-------------|
| Marketing | ~$0.45 |
| Utility | ~$0.25 |
| Authentication | ~$0.20 |
| Service (respuesta 24h) | Gratis |

---

## Definition of Ready (DoR)

- [x] Historias de usuario definidas
- [x] Criterios de aceptacion claros
- [x] Dependencias identificadas
- [x] Estimacion completada
- [ ] Cuenta Meta Business verificada
- [ ] Numero WhatsApp Business registrado
- [ ] App en Meta Developers creada
- [x] Sin bloqueadores activos

## Definition of Done (DoD)

- [ ] Codigo implementado y revisado
- [ ] Tests pasando (unit, integration)
- [ ] Webhooks recibiendo mensajes
- [ ] Envio de mensajes funcional
- [ ] Templates creandose correctamente
- [ ] Chatbot basico funcionando
- [ ] Documentacion actualizada
- [ ] Inventarios actualizados
- [ ] Demo realizada
- [ ] Product Owner aprobo

---

## Documentacion Relacionada

- Requerimientos: `docs/03-requerimientos/RF-whatsapp/`
- User Stories: `docs/05-user-stories/mgn-018/`
- DDL Spec: `docs/04-modelado/database-design/DDL-SPEC-messaging.md`
- API Meta: https://developers.facebook.com/docs/whatsapp/cloud-api

---

## Historial

| Fecha | Cambio | Autor |
|-------|--------|-------|
| 2025-12-05 | Creacion de epica | Requirements-Analyst |
| 2025-12-05 | Completado con Stakeholders, Riesgos, Costos | Requirements-Analyst |

---

**Creada por:** Requirements-Analyst
**Fecha:** 2025-12-05
**Ultima actualizacion:** 2025-12-05