rckrdmrd 928eb795e6 [SIMCO-V38] feat: Actualizar a SIMCO v3.8.0 + cambios apps

- HERENCIA-SIMCO.md actualizado con directivas v3.7 y v3.8
- Cambios en backend y frontend

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-10 08:53:05 -06:00

6.1 KiB

Raw Blame History

MCH-011: WhatsApp Service

Metadata

Codigo: MCH-011
Fase: 3 - Asistente IA
Prioridad: P0
Estado: Completado
Fecha completado: 2026-01-10

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

Integracion Meta WhatsApp Business API
Webhooks para mensajes entrantes
Envio de mensajes/templates
Multi-numero por tenant
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)

Excluido

WhatsApp Web (no oficial)
Grupos de WhatsApp
Estados/historias
Llamadas de voz/video

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

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

6.1 KiB Raw Blame History