template-saas/orchestration/_archivo/planes/PLAN-SPRINT-5-WHATSAPP.md

PLAN SPRINT 5 - WhatsApp Business API

Proyecto: template-saas Sprint: 5 Objetivo: Integrar WhatsApp Business API para notificaciones Fecha Inicio: 2026-01-10 SP Total: 13

---

RESUMEN EJECUTIVO

Estado Actual

• Canales de notificación: Email, Push, In-app, WebSocket
• WhatsApp: No integrado
• SMS: No integrado

Gap a Cerrar

Integrar WhatsApp Business API como canal de notificaciones:

1. Provider de WhatsApp (Meta Cloud API)
2. Templates de mensajes aprobados
3. Webhook para status de entrega
4. UI de configuración por tenant
5. Tests de integración

---

TAREAS DEL SPRINT

WA-001: WhatsApp Provider Backend

Agente: Backend-Agent SP: 5 Dependencia: Ninguna

Archivos a Leer

archivos:
  - apps/backend/src/modules/email/services/email.service.ts
  - apps/backend/src/modules/notifications/services/notifications.service.ts
  - apps/database/ddl/02-enums.sql

Entregables

entregables:
  - apps/backend/src/modules/whatsapp/whatsapp.module.ts
  - apps/backend/src/modules/whatsapp/services/whatsapp.service.ts
  - apps/backend/src/modules/whatsapp/services/whatsapp-template.service.ts
  - apps/backend/src/modules/whatsapp/controllers/whatsapp-webhook.controller.ts
  - apps/backend/src/modules/whatsapp/dto/send-whatsapp.dto.ts
  - apps/backend/src/modules/whatsapp/dto/whatsapp-webhook.dto.ts
  - apps/backend/src/modules/whatsapp/__tests__/whatsapp.service.spec.ts

Funcionalidades

• Envío de mensajes de texto
• Envío de mensajes con template
• Webhook para delivery status
• Rate limiting por tenant
• Retry logic para fallos

---

WA-002: DDL WhatsApp

Agente: Database-Agent SP: 2 Dependencia: Ninguna Paralelo con: WA-001

Entregables

entregables:
  - apps/database/ddl/schemas/whatsapp/tables/01-whatsapp-configs.sql
  - apps/database/ddl/schemas/whatsapp/tables/02-whatsapp-messages.sql
  - apps/database/ddl/02-enums.sql (actualizar)

Tablas

• whatsapp.configs - Configuración por tenant (phone_number_id, access_token)
• whatsapp.messages - Log de mensajes enviados

Enums

• whatsapp.message_status: 'pending', 'sent', 'delivered', 'read', 'failed'
• whatsapp.message_type: 'text', 'template', 'media'

---

WA-003: Entidades TypeORM

Agente: Backend-Agent SP: 2 Dependencia: WA-002

Entregables

entregables:
  - apps/backend/src/modules/whatsapp/entities/whatsapp-config.entity.ts
  - apps/backend/src/modules/whatsapp/entities/whatsapp-message.entity.ts

---

WA-004: Frontend WhatsApp Config

Agente: Frontend-Agent SP: 2 Dependencia: WA-001

Entregables

entregables:
  - apps/frontend/src/pages/admin/WhatsAppSettings.tsx
  - apps/frontend/src/hooks/useWhatsApp.ts
  - apps/frontend/src/services/whatsapp.api.ts
  - apps/frontend/src/components/whatsapp/WhatsAppTestMessage.tsx

Funcionalidades

• Configuración de credenciales Meta
• Test de conexión
• Envío de mensaje de prueba
• Ver historial de mensajes

---

WA-005: Integración Notifications

Agente: Backend-Agent SP: 2 Dependencia: WA-001, WA-003

Entregables

entregables:
  - apps/backend/src/modules/notifications/services/notifications.service.ts (modificar)
  - apps/backend/src/modules/notifications/dto/send-notification.dto.ts (modificar)

Cambios

• Agregar 'whatsapp' al enum de canales
• Integrar WhatsAppService en NotificationsService
• Validar que tenant tenga WhatsApp configurado

---

CONFIGURACIÓN META CLOUD API

Variables de Entorno

WHATSAPP_API_VERSION=v17.0
WHATSAPP_VERIFY_TOKEN=your_verify_token
# Per-tenant configs stored in DB

Webhook Events

• messages - Mensajes entrantes
• message_status - Updates de status (sent, delivered, read)

---

EJECUCIÓN DEL SPRINT

Orden de Ejecución

WA-002 (DDL)
    │
    └── WA-003 (Entities)
            │
WA-001 (Backend) ──────────┤
    │                      │
    ├── WA-004 (Frontend)  │
    │                      │
    └── WA-005 (Integration)

Comandos de Validación

# Tests del módulo
cd apps/backend && npm run test -- --testPathPattern=whatsapp

# Recrear BD con nuevo schema
cd apps/database && FORCE=1 ./scripts/drop-and-recreate.sh

Métricas de Éxito

Métrica	Objetivo
Endpoints nuevos	5-6
Tests nuevos	~20
Tablas nuevas	2
Webhook funcional	SI

---

ESTRUCTURA DE ARCHIVOS

apps/backend/src/modules/whatsapp/
├── whatsapp.module.ts
├── services/
│   ├── whatsapp.service.ts
│   └── whatsapp-template.service.ts
├── controllers/
│   └── whatsapp-webhook.controller.ts
├── entities/
│   ├── whatsapp-config.entity.ts
│   └── whatsapp-message.entity.ts
├── dto/
│   ├── send-whatsapp.dto.ts
│   └── whatsapp-webhook.dto.ts
└── __tests__/
    └── whatsapp.service.spec.ts

apps/database/ddl/schemas/whatsapp/
├── tables/
│   ├── 01-whatsapp-configs.sql
│   └── 02-whatsapp-messages.sql

---

REFERENCIAS

• Meta Cloud API Docs
• Webhook Reference
• Message Templates

---

Creado: 2026-01-10 Sprint: 5 de 5 Estado: COMPLETADO

---

REPORTE DE EJECUCION

Fecha Completado: 2026-01-10

Entregables Generados

WA-002: DDL WhatsApp

Archivo	Estado
apps/database/ddl/schemas/whatsapp/00-schema.sql	Creado
apps/database/ddl/schemas/whatsapp/tables/01-whatsapp-configs.sql	Creado
apps/database/ddl/schemas/whatsapp/tables/02-whatsapp-messages.sql	Creado

WA-003: Entidades TypeORM

Archivo	Estado
apps/backend/src/modules/whatsapp/entities/whatsapp-config.entity.ts	Creado
apps/backend/src/modules/whatsapp/entities/whatsapp-message.entity.ts	Creado

WA-001: Backend WhatsApp Module

Archivo	Estado
apps/backend/src/modules/whatsapp/whatsapp.module.ts	Creado
apps/backend/src/modules/whatsapp/services/whatsapp.service.ts	Creado
apps/backend/src/modules/whatsapp/controllers/whatsapp.controller.ts	Creado
apps/backend/src/modules/whatsapp/controllers/whatsapp-webhook.controller.ts	Creado
apps/backend/src/modules/whatsapp/dto/send-whatsapp.dto.ts	Creado
apps/backend/src/modules/whatsapp/dto/whatsapp-webhook.dto.ts	Creado
apps/backend/src/modules/whatsapp/dto/whatsapp-config.dto.ts	Creado
apps/backend/src/modules/whatsapp/tests/whatsapp.service.spec.ts	Creado

WA-004: Frontend WhatsApp

Archivo	Estado
apps/frontend/src/pages/admin/WhatsAppSettings.tsx	Creado
apps/frontend/src/hooks/useWhatsApp.ts	Creado
apps/frontend/src/services/whatsapp.api.ts	Creado
apps/frontend/src/components/whatsapp/WhatsAppTestMessage.tsx	Creado

WA-005: Integration Notifications

Archivo	Cambio
apps/backend/src/modules/notifications/dto/create-notification.dto.ts	Agregado 'whatsapp' al enum de canales
apps/backend/src/modules/notifications/services/notifications.service.ts	Integrado WhatsAppService

Funcionalidades Implementadas

1. Configuracion por Tenant

   • CRUD de configuracion WhatsApp Business API
   • Verificacion automatica de credenciales
   • Rate limiting configurable

2. Envio de Mensajes

   • Mensajes de texto
   • Mensajes con template
   • Mensajes multimedia (imagen, documento, audio, video)

3. Webhook Handler

   • Verificacion de webhook Meta
   • Procesamiento de mensajes entrantes
   • Actualizacion de status de delivery

4. Frontend Admin

   • Pagina de configuracion
   • Prueba de conexion
   • Historial de mensajes

Metricas Finales

Metrica	Objetivo	Resultado
Tablas DDL	2	2
Entidades	2	2
Endpoints API	5-6	8
Tests	~20	22
SP completados	13	13