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

id	type	title	code	status	phase	priority	created_at	updated_at	simco_version	story_points	dependencies
EPIC-MCH-011	Epic	MCH-011: WhatsApp Service	MCH-011	Completado	3	P0	2026-01-10	2026-01-17	4.0.1	55	blocks depends_on MCH-001 MCH-002 MCH-010

MCH-011: WhatsApp Service

Metadata

• Codigo: MCH-011
• Fase: 3 - Asistente IA
• Prioridad: P0
• Estado: Completado
• Fecha completado: 2026-01-10
• Story Points: 55
• SIMCO Version: 4.0.1

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	En progreso	apps/whatsapp-service/
Webhook handler	En progreso	handlers/webhook.handler.ts
Message processor	Pendiente	workers/message.worker.ts
Template service	Pendiente	services/template.service.ts

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

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

Configuracion por Tenant

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