# 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

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)

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

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