michangarrito/docs/01-epicas/MCH-011-whatsapp-service.md

---
id: EPIC-MCH-011
type: Epic
title: "MCH-011: WhatsApp Service"
code: MCH-011
status: Completado
status_real: Completado
status_nota: "NestJS service completo con webhook, multi-tenant, LLM integration"
phase: 3
priority: P0
created_at: 2026-01-10
updated_at: 2026-01-17
completed_at: 2026-01-17
simco_version: "4.0.1"
story_points: 55
dependencies:
  blocks: ["MCH-012", "MCH-013", "MCH-015", "MCH-017"]
  depends_on:
    - MCH-001
    - MCH-002
---

# MCH-011: WhatsApp Service

## Metadata
- **Codigo:** MCH-011
- **Fase:** 3 - Asistente IA
- **Prioridad:** P0 (BLOQUEANTE)
- **Estado:** Completado
- **Estado Real:** NestJS service completo - 4 módulos, 5 servicios
- **Story Points:** 55
- **Sprint Asignado:** Sprint 1 (Desbloqueo Crítico)
- **SIMCO Version:** 4.0.1
- **Completado:** 2026-01-17

## Descripcion

Servicio de integracion con WhatsApp Business API de Meta. Permite a los negocios recibir y enviar mensajes, procesar pedidos, enviar notificaciones, y conectar con el asistente IA.

## Objetivos

1. Integracion Meta WhatsApp Business API
2. Webhooks para mensajes entrantes
3. Envio de mensajes/templates
4. Multi-numero por tenant
5. Conexion con MCP Server

## Alcance

### Incluido
- WhatsApp Business API (Cloud)
- Recepcion de mensajes (texto, audio, imagen)
- Envio de mensajes y templates
- Procesamiento via MCP Server
- Webhooks verificados
- Cola de mensajes (Redis)
- Multi-tenant con routing por numero
- Manejo de diferentes tipos de mensaje
- Procesamiento asincrono con workers

### Excluido
- WhatsApp Web (no oficial)
- Grupos de WhatsApp
- Estados/historias
- Llamadas de voz/video
- Integracion con redes sociales adicionales

## Arquitectura

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Cliente   │────▶│    Meta     │────▶│   Webhook   │
│  WhatsApp   │◀────│  Cloud API  │◀────│   Handler   │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                                        ┌──────▼──────┐
                                        │    Redis    │
                                        │   (Queue)   │
                                        └──────┬──────┘
                                               │
                                        ┌──────▼──────┐
                                        │  Processor  │
                                        │   Worker    │
                                        └──────┬──────┘
                                               │
                    ┌──────────────────────────┼──────────────────────────┐
                    │                          │                          │
             ┌──────▼──────┐           ┌───────▼───────┐          ┌──────▼──────┐
             │ MCP Server  │           │   Backend     │          │  Templates  │
             │  (Chat IA)  │           │     API       │          │   Service   │
             └─────────────┘           └───────────────┘          └─────────────┘
```

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /whatsapp/webhook | Webhook de Meta |
| GET | /whatsapp/webhook | Verificacion webhook |
| POST | /whatsapp/send | Enviar mensaje |
| POST | /whatsapp/template | Enviar template |
| GET | /whatsapp/conversations | Conversaciones |
| GET | /whatsapp/messages/:conversationId | Mensajes |

## Tipos de Mensaje

### Entrantes
- **text**: Mensaje de texto
- **audio**: Nota de voz (se transcribe)
- **image**: Imagen (OCR si aplica)
- **location**: Ubicacion (para entregas)
- **interactive**: Respuesta de botones/lista

### Salientes
- **text**: Mensaje de texto
- **template**: Mensaje pre-aprobado
- **interactive**: Botones o lista
- **media**: Imagen, documento, audio

## Templates Pre-aprobados

### Recordatorio de Pago
```
Hola {{1}}, te recordamos que tienes un saldo
pendiente de ${{2}} en {{3}}.
¿Cuando podrias pasar a liquidar?
```

### Confirmacion de Pedido
```
¡Pedido recibido! 🛒

{{1}}

Total: ${{2}}
Entrega estimada: {{3}}

¿Confirmas tu pedido?
[Si, confirmar] [Cancelar]
```

### Pedido Listo
```
¡Tu pedido esta listo! 📦

Puedes pasar a recogerlo a {{1}}
o lo enviamos a tu domicilio.

[Voy para alla] [Enviar a domicilio]
```

## Modelo de Datos

### Tablas (schema: messaging)

**conversations**
- id, tenant_id, customer_phone
- wa_conversation_id, status
- last_message_at, metadata

**messages**
- id, conversation_id, direction (in/out)
- type, content, status
- wa_message_id, created_at

## Flujos

### Mensaje Entrante
```
1. Meta envia POST a /webhook
2. Validamos firma del request
3. Extraemos mensaje y metadata
4. Encolamos en Redis
5. Worker procesa:
   a. Identifica tenant por numero
   b. Busca/crea conversacion
   c. Si es texto: envia a MCP
   d. Si es audio: transcribe, luego MCP
   e. Si es imagen: OCR si necesario
6. MCP responde con accion
7. Enviamos respuesta al cliente
```

### Envio de Notificacion
```
1. Backend trigger (ej: recordatorio fiado)
2. Busca template apropiado
3. Llena variables
4. POST a Meta API
5. Registra en BD
6. Espera delivery report
```

## Historias de Usuario

### MCH-US-100: Webhook de Meta para recepcion de mensajes
**Story Points:** 8

**Como** administrador del servicio WhatsApp
**Quiero** recibir mensajes desde Meta en un webhook verificado
**Para** procesar mensajes entrantes de clientes de forma confiable

#### Criterios de Aceptacion
- [CA-100-1] El endpoint POST /whatsapp/webhook recibe payloads de Meta
- [CA-100-2] Se valida la firma HMAC del request con verify_token
- [CA-100-3] Se retorna 200 OK para requests validos
- [CA-100-4] Se registra cada mensaje recibido en logs
- [CA-100-5] El endpoint GET /whatsapp/webhook responde challenge token para verificacion inicial

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-100-01 | Crear controller webhook con validacion HMAC | 3h |
| MCH-TT-100-02 | Implementar verificacion de challenge token | 2h |
| MCH-TT-100-03 | Agregar logging y monitoreo de requests | 2h |
| MCH-TT-100-04 | Tests unitarios de validacion | 1h |

### MCH-US-101: Procesamiento de tipos de mensaje entrante
**Story Points:** 13

**Como** procesador de mensajes
**Quiero** diferenciar y procesar distintos tipos de mensaje (texto, audio, imagen, ubicacion)
**Para** aplicar logica especifica a cada tipo

#### Criterios de Aceptacion
- [CA-101-1] Texto se extrae y envia a MCP directamente
- [CA-101-2] Audio se descarga de Meta y se transcribe con speech-to-text
- [CA-101-3] Imagen se descarga y se procesa con OCR si es necesario
- [CA-101-4] Ubicacion se extrae como coordenadas para entregas
- [CA-101-5] Interactive (botones/lista) se registra como respuesta seleccionada
- [CA-101-6] Mensajes no soportados retornan error al usuario

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-101-01 | Parser de payloads segun tipo de mensaje | 3h |
| MCH-TT-101-02 | Integracion con speech-to-text para audio | 4h |
| MCH-TT-101-03 | Integracion con OCR para imagenes | 3h |
| MCH-TT-101-04 | Manejo de ubicaciones y coordenadas | 2h |
| MCH-TT-101-05 | Tests de parseo para cada tipo | 1h |

### MCH-US-102: Cola de mensajes con Redis
**Story Points:** 8

**Como** procesador asincrono
**Quiero** encolar mensajes en Redis para procesamiento no bloqueante
**Para** garantizar entrega y poder procesar picos de volumen

#### Criterios de Aceptacion
- [CA-102-1] Cada mensaje webhook se enqueuea en Redis inmediatamente
- [CA-102-2] La cola tiene nombre por tenant (ej: whatsapp:messages:{tenantId})
- [CA-102-3] Se registra timestamp de enqueue
- [CA-102-4] Se implementa retry automatico en caso de fallo
- [CA-102-5] Se monitorea longitud de la cola

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-102-01 | Crear consumer de Redis para WhatsApp | 2h |
| MCH-TT-102-02 | Implementar logica de enqueue en webhook | 2h |
| MCH-TT-102-03 | Manejo de retries y fallidos | 2h |
| MCH-TT-102-04 | Monitoreo y alertas de cola | 2h |

### MCH-US-103: Procesamiento de mensajes con MCP Server
**Story Points:** 10

**Como** worker de procesamiento
**Quiero** enviar mensajes a MCP Server para respuestas con IA
**Para** proporcionar respuestas inteligentes a clientes

#### Criterios de Aceptacion
- [CA-103-1] El worker consume mensajes de la cola Redis
- [CA-103-2] Envía mensaje a MCP Server (texto o transcripcion)
- [CA-103-3] Recibe respuesta del MCP
- [CA-103-4] Registra la conversacion y respuesta en BD
- [CA-103-5] Maneja timeout si MCP no responde
- [CA-103-6] Registra errores sin detener el worker

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-103-01 | Worker que consume de Redis | 3h |
| MCH-TT-103-02 | Cliente HTTP para MCP Server | 2h |
| MCH-TT-103-03 | Persistencia de conversaciones | 2h |
| MCH-TT-103-04 | Manejo de errores y timeouts | 2h |
| MCH-TT-103-05 | Tests de integracion | 1h |

### MCH-US-104: Multi-tenant con routing por numero
**Story Points:** 9

**Como** servicio multi-tenant
**Quiero** identificar el tenant segun el numero de WhatsApp de destino
**Para** garantizar aislamiento de datos entre negocios

#### Criterios de Aceptacion
- [CA-104-1] Se busca tenant_id por numero de telefono en tenant_integrations
- [CA-104-2] Si no existe, se rechaza el mensaje (no valido)
- [CA-104-3] Se asocia cada mensaje a su tenant_id en BD
- [CA-104-4] La cola de Redis es por tenant
- [CA-104-5] MCP context incluye tenant_id para respuestas contextualizadas

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-104-01 | Mapper de numero a tenant_id | 2h |
| MCH-TT-104-02 | Validacion y rechazo de numeros desconocidos | 2h |
| MCH-TT-104-03 | Aislamiento en BD con tenant_id | 2h |
| MCH-TT-104-04 | Tests de routing multi-tenant | 3h |

### MCH-US-105: Envio de mensajes de texto
**Story Points:** 6

**Como** backend o trigger de negocio
**Quiero** enviar mensajes de texto simples a clientes
**Para** notificar estados, recordatorios, etc.

#### Criterios de Aceptacion
- [CA-105-1] Endpoint POST /whatsapp/send acepta numero y contenido
- [CA-105-2] Se valida numero de telefono valido
- [CA-105-3] Se envia a Meta API con access_token correcto
- [CA-105-4] Se registra el mensaje en BD con estado pending
- [CA-105-5] Se retorna message_id de Meta para tracking

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-105-01 | Controller POST /whatsapp/send | 2h |
| MCH-TT-105-02 | Validacion de numero de telefono | 1h |
| MCH-TT-105-03 | Cliente de Meta API para envio | 2h |
| MCH-TT-105-04 | Tests de envio | 1h |

### MCH-US-106: Envio de templates pre-aprobados
**Story Points:** 11

**Como** backend de negocio
**Quiero** enviar templates pre-aprobados por Meta con variables
**Para** notificaciones con formato consistente sin reenvios

#### Criterios de Aceptacion
- [CA-106-1] Se cargan templates desde BD (recordatorio, confirmacion pedido, etc.)
- [CA-106-2] Endpoint POST /whatsapp/template acepta template_name y parametros
- [CA-106-3] Se valida que template existe y esta aprobado por Meta
- [CA-106-4] Se reemplazan variables {{1}}, {{2}}, etc. correctamente
- [CA-106-5] Se envia a Meta API
- [CA-106-6] Se registra en BD para auditoria

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-106-01 | Modelo de datos para templates | 2h |
| MCH-TT-106-02 | Loader de templates desde BD | 2h |
| MCH-TT-106-03 | Parser y reemplazo de variables | 2h |
| MCH-TT-106-04 | Controller POST /whatsapp/template | 2h |
| MCH-TT-106-05 | Tests de templates | 3h |

### MCH-US-107: Historial de conversaciones
**Story Points:** 8

**Como** cliente o admin
**Quiero** ver el historial de conversaciones con cada numero
**Para** mantener contexto y auditoria de interacciones

#### Criterios de Aceptacion
- [CA-107-1] Endpoint GET /whatsapp/conversations lista conversaciones del tenant
- [CA-107-2] Cada conversacion muestra ultimo mensaje y timestamp
- [CA-107-3] Endpoint GET /whatsapp/messages/:conversationId lista mensajes ordenados
- [CA-107-4] Se filtra por rango de fechas (opcional)
- [CA-107-5] Se muestra direccion (in/out), tipo y estado de cada mensaje

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-107-01 | Controller GET /whatsapp/conversations | 2h |
| MCH-TT-107-02 | Controller GET /whatsapp/messages/:id | 2h |
| MCH-TT-107-03 | Queries optimizadas en BD | 2h |
| MCH-TT-107-04 | Tests de paginacion y filtros | 2h |

### MCH-US-108: Delivery reports y confirmacion de estado
**Story Points:** 7

**Como** backend
**Quiero** recibir webhooks de Meta con status de delivery
**Para** actualizar estado de mensajes enviados

#### Criterios de Aceptacion
- [CA-108-1] Meta envia webhook con message_status (sent, delivered, read, failed)
- [CA-108-2] Se actualiza estado en tabla messages
- [CA-108-3] Se maneja failed con reintento opcional
- [CA-108-4] Se log cada cambio de estado
- [CA-108-5] Se notifica al cliente si es necesario

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-108-01 | Handler de status webhook | 2h |
| MCH-TT-108-02 | Logica de actualizacion de estado | 2h |
| MCH-TT-108-03 | Manejo de reintentos | 2h |
| MCH-TT-108-04 | Tests de delivery reports | 1h |

### MCH-US-109: Configuracion y credenciales por tenant
**Story Points:** 5

**Como** admin de tenant
**Quiero** almacenar y gestionar credenciales de Meta de forma segura
**Para** habilitar WhatsApp en mi negocio sin exponer secrets

#### Criterios de Aceptacion
- [CA-109-1] Credenciales se almacenan encriptadas en tenant_integrations
- [CA-109-2] phone_number_id, access_token, verify_token se persisten
- [CA-109-3] Endpoint para actualizar credenciales con validacion
- [CA-109-4] Nunca se retornan credenciales en respuestas de API
- [CA-109-5] Se registra auditar cuando se cambian credenciales

#### Tareas
| ID | Tarea | Estimación |
|----|-------|------------|
| MCH-TT-109-01 | Migracion de schema para encriptacion | 1h |
| MCH-TT-109-02 | Service de gestion de credenciales | 2h |
| MCH-TT-109-03 | Endpoint PUT /whatsapp/credentials | 1h |
| MCH-TT-109-04 | Tests de seguridad | 1h |

### Resumen de Story Points
| Historia | Descripción | SP |
|----------|-------------|-----|
| MCH-US-100 | Webhook de Meta para recepcion de mensajes | 8 |
| MCH-US-101 | Procesamiento de tipos de mensaje entrante | 13 |
| MCH-US-102 | Cola de mensajes con Redis | 8 |
| MCH-US-103 | Procesamiento de mensajes con MCP Server | 10 |
| MCH-US-104 | Multi-tenant con routing por numero | 9 |
| MCH-US-105 | Envio de mensajes de texto | 6 |
| MCH-US-106 | Envio de templates pre-aprobados | 11 |
| MCH-US-107 | Historial de conversaciones | 8 |
| MCH-US-108 | Delivery reports y confirmacion de estado | 7 |
| MCH-US-109 | Configuracion y credenciales por tenant | 5 |
| **Total** | | **85** |

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| WhatsApp Service (NestJS) | Completado | `whatsapp-service/` |
| Webhook Controller | Completado | `src/webhook/webhook.controller.ts` |
| Webhook Service | Completado | `src/webhook/webhook.service.ts` |
| WhatsApp Service | Completado | `src/whatsapp/whatsapp.service.ts` |
| LLM Service | Completado | `src/llm/llm.service.ts` |
| Credentials Provider | Completado | `src/common/credentials-provider.service.ts` |
| WhatsApp Interfaces | Completado | `src/whatsapp/interfaces/whatsapp.interface.ts` |

### Funcionalidades Implementadas

| Historia | Descripcion | Estado |
|----------|-------------|--------|
| MCH-US-100 | Webhook Meta con verificacion HMAC | ✅ Completado |
| MCH-US-101 | Procesamiento tipos mensaje (text, audio, image, location) | ✅ Completado |
| MCH-US-102 | Cola mensajes (in-memory, sin Redis) | ⚠️ Simplificado |
| MCH-US-103 | Procesamiento con LLM (OpenAI/OpenRouter) | ✅ Completado |
| MCH-US-104 | Multi-tenant routing por phoneNumberId | ✅ Completado |
| MCH-US-105 | Envio mensajes texto | ✅ Completado |
| MCH-US-106 | Envio templates | ✅ Completado |
| MCH-US-107 | Historial conversaciones (in-memory) | ✅ Completado |
| MCH-US-108 | Delivery reports y status | ✅ Completado |
| MCH-US-109 | Credenciales encriptadas por tenant | ✅ Completado |

## Dependencias

### Depende de
- MCH-001 (Infraestructura)
- MCH-002 (Auth)
- MCH-010 (MCP Server)

### Bloquea a
- MCH-006 (Onboarding via WhatsApp)
- MCH-012 (Chat dueno)
- MCH-013 (Chat cliente)
- MCH-015 (Pedidos via WhatsApp)

## Criterios de Aceptacion

- [x] Webhook recibe mensajes correctamente
- [x] Mensajes se procesan via MCP
- [x] Templates se envian correctamente
- [x] Multi-tenant funciona (routing por numero)
- [x] Audio se transcribe correctamente

## Configuracion por Tenant

```typescript
// tenant_integrations
{
  provider: 'whatsapp',
  credentials: {
    phone_number_id: '...',
    access_token: 'encrypted...',
    verify_token: '...'
  },
  settings: {
    business_name: 'Mi Tiendita',
    auto_reply: true,
    ai_enabled: true
  }
}
```

## Puerto

- **WhatsApp Service:** 3143

---

**Ultima actualizacion:** 2026-01-17