rckrdmrd
928eb795e6
- 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>
220 lines
6.1 KiB
Markdown
220 lines
6.1 KiB
Markdown
# 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
|