WhatsAppCentralizado/docs/plans/2026-01-29-whatsapp-centralizado-design.md

# WhatsApp Centralizado - Documento de Diseño

**Fecha:** 2026-01-29
**Versión:** 1.0
**Estado:** Aprobado para implementación

---

## 1. Resumen Ejecutivo

Plataforma de mensajería centralizada con automatización de chatbots, gestión multi-agente e integración profunda con Odoo. Similar a Kommo, Wasapi, ManyChat y Brevo pero con enfoque en integración empresarial.

### Decisiones Clave

| Aspecto | Decisión |
|---------|----------|
| **Enfoque** | Chatbots + Multi-agente + Multi-canal |
| **Canal inicial** | WhatsApp (Baileys) |
| **Stack backend** | Node.js (WhatsApp) + Python/FastAPI (API) |
| **Stack frontend** | React + TypeScript |
| **Base de datos** | PostgreSQL + Redis |
| **Editor chatbot** | Visual drag & drop (React Flow) |
| **Modelo** | Single-tenant |
| **Despliegue** | Docker Compose en servidores propios |
| **Integración principal** | Odoo (bidireccional) |

---

## 2. Arquitectura General

```
┌─────────────────────────────────────────────────────────────────┐
│                        FRONTEND (React)                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   Dashboard │  │  Inbox Chat │  │  Flow Builder (React    │  │
│  │             │  │  (Agentes)  │  │  Flow)                  │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    API GATEWAY (Python/FastAPI)                  │
│  • Autenticación JWT  • REST API  • WebSocket para tiempo real  │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
┌──────────────────┐ ┌──────────────┐ ┌──────────────────────────┐
│  WHATSAPP CORE   │ │  FLOW ENGINE │ │  INTEGRATION SERVICE     │
│  (Node.js +      │ │  (Python)    │ │  (Python)                │
│  Baileys)        │ │  Motor de    │ │  • Webhooks              │
│  • Multi-número  │ │  chatbot     │ │  • Odoo XML-RPC          │
│  • Sesiones      │ │              │ │  • APIs externas         │
└──────────────────┘ └──────────────┘ └──────────────────────────┘
              │               │               │
              └───────────────┼───────────────┘
                              ▼
                    ┌──────────────────┐
                    │ PostgreSQL+Redis │
                    └──────────────────┘
```

---

## 3. Estructura del Proyecto

```
WhatsAppCentralizado/
├── docker-compose.yml
├── .env.example
│
├── services/
│   ├── whatsapp-core/          # Node.js + Baileys
│   │   ├── Dockerfile
│   │   ├── package.json
│   │   └── src/
│   │       ├── index.ts
│   │       ├── sessions/       # Gestión de sesiones WhatsApp
│   │       ├── handlers/       # Procesamiento de mensajes
│   │       └── api/            # API interna
│   │
│   ├── api-gateway/            # Python + FastAPI
│   │   ├── Dockerfile
│   │   ├── requirements.txt
│   │   └── app/
│   │       ├── main.py
│   │       ├── routers/
│   │       ├── models/
│   │       ├── schemas/
│   │       └── services/
│   │
│   ├── flow-engine/            # Python - Motor de chatbot
│   │   ├── Dockerfile
│   │   └── app/
│   │       ├── engine.py
│   │       ├── nodes/
│   │       └── context.py
│   │
│   └── integrations/           # Python - Integraciones
│       ├── Dockerfile
│       └── app/
│           ├── odoo.py
│           └── webhooks.py
│
├── frontend/                   # React + TypeScript
│   ├── Dockerfile
│   ├── package.json
│   └── src/
│       ├── pages/
│       │   ├── Dashboard/
│       │   ├── Inbox/
│       │   └── FlowBuilder/
│       ├── components/
│       └── hooks/
│
└── database/
    └── migrations/
```

---

## 4. Modelo de Datos

### 4.1 Tablas Principales

```sql
-- Usuarios y Autenticación
users
├── id (UUID, PK)
├── email (UNIQUE)
├── password_hash
├── name
├── role (admin, supervisor, agent)
├── status (online, away, busy, offline)
├── is_active
├── created_at
└── updated_at

-- Números de WhatsApp conectados
whatsapp_accounts
├── id (UUID, PK)
├── phone_number
├── name (alias)
├── status (connected, disconnected, banned)
├── session_data (JSONB)
├── qr_code (TEXT)
└── created_at

-- Contactos
contacts
├── id (UUID, PK)
├── phone_number (UNIQUE)
├── name
├── email
├── company
├── metadata (JSONB)
├── tags (ARRAY)
├── odoo_partner_id (INT)
└── created_at

-- Colas de atención
queues
├── id (UUID, PK)
├── name
├── description
├── assignment_method (round_robin, least_busy, skill_based)
├── max_per_agent (INT)
├── sla_first_response (INT, segundos)
├── sla_resolution (INT, segundos)
├── business_hours (JSONB)
├── fallback_flow_id (FK)
└── is_active

-- Agentes en colas
queue_agents
├── id (UUID, PK)
├── queue_id (FK)
├── user_id (FK)
├── is_supervisor
└── skills (ARRAY)

-- Conversaciones
conversations
├── id (UUID, PK)
├── whatsapp_account_id (FK)
├── contact_id (FK)
├── queue_id (FK, nullable)
├── assigned_to (FK → users, nullable)
├── status (bot, waiting, active, resolved)
├── priority (low, normal, high, urgent)
├── current_flow_id (FK, nullable)
├── flow_context (JSONB)
├── sla_first_response_at (TIMESTAMP)
├── sla_first_response_met (BOOLEAN)
├── resolved_at (TIMESTAMP)
├── csat_score (INT, 1-5)
├── csat_feedback (TEXT)
├── last_message_at
└── created_at

-- Mensajes
messages
├── id (UUID, PK)
├── conversation_id (FK)
├── direction (inbound, outbound)
├── type (text, image, audio, video, document, buttons, list, location, contact)
├── content (TEXT)
├── media_url
├── metadata (JSONB)
├── sent_by (FK → users, nullable)
├── is_internal_note (BOOLEAN)
├── status (pending, sent, delivered, read, failed)
└── created_at

-- Flujos de chatbot
flows
├── id (UUID, PK)
├── name
├── description
├── trigger_type (keyword, welcome, fallback, manual, event)
├── trigger_value
├── nodes (JSONB)
├── variables (JSONB)
├── is_active
├── version (INT)
└── created_at

-- Templates de mensajes
message_templates
├── id (UUID, PK)
├── name
├── content (TEXT)
├── attachments (JSONB)
├── variables (ARRAY)
└── created_at

-- Respuestas rápidas
quick_replies
├── id (UUID, PK)
├── shortcut
├── content
├── attachments (JSONB)
├── queue_id (FK, nullable)
├── created_by (FK)
└── created_at

-- Etiquetas
tags
├── id (UUID, PK)
├── name
├── color
└── created_at

-- Configuración Odoo
odoo_config
├── id (UUID, PK)
├── url
├── database
├── username
├── api_key_encrypted
├── is_active
├── last_sync_at
└── created_at

-- Automatizaciones Odoo → WhatsApp
odoo_automations
├── id (UUID, PK)
├── name
├── odoo_model (sale.order, stock.picking, etc.)
├── odoo_trigger (state change, field change)
├── odoo_condition (JSONB)
├── message_template_id (FK)
├── is_active
└── created_at
```

---

## 5. Flow Builder

### 5.1 Tipos de Nodos

#### Nodos de Trigger
- `welcome` - Primer mensaje del contacto
- `keyword` - Palabras clave específicas
- `fallback` - Cuando ningún otro flujo coincide
- `event` - Evento externo (webhook, Odoo)
- `schedule` - Horario programado

#### Nodos de Mensaje
- `text` - Texto con variables y formateo
- `image` - Imagen con caption
- `video` - Video con caption
- `audio` - Audio/nota de voz
- `document` - PDF, Excel, Word
- `location` - Ubicación
- `contact` - Tarjeta de contacto
- `sticker` - Stickers
- `buttons` - Hasta 3 botones
- `list` - Lista con secciones (hasta 10 opciones)
- `template` - Mensaje reutilizable
- `carousel` - Múltiples tarjetas

#### Nodos de Lógica
- `condition` - Condiciones múltiples (AND/OR/NOT)
- `switch` - Múltiples ramas según valor
- `wait_input` - Esperar respuesta con timeout
- `wait_event` - Esperar evento externo
- `delay` - Delay fijo o aleatorio
- `schedule` - Ejecutar en horario específico
- `random` - A/B testing
- `loop` - Repetir bloque
- `set_variable` - Asignar/modificar variables
- `javascript` - Código custom
- `go_to` - Saltar a otro flujo/nodo
- `sub_flow` - Ejecutar sub-flujo

#### Nodos de Validación
- `validate_email` - Formato email
- `validate_phone` - Formato teléfono
- `validate_number` - Rango numérico
- `validate_date` - Fecha/hora
- `validate_regex` - Expresión regular
- `validate_options` - Lista de opciones
- `retry_input` - Reintentar con mensaje error

#### Nodos de Acción
- `transfer` - Transferir a agente/cola
- `close` - Cerrar conversación
- `tag` - Agregar/quitar etiquetas
- `note` - Nota interna
- `assign` - Asignar a agente
- `notify` - Notificar a agente/admin
- `webhook` - HTTP request
- `odoo_action` - Acciones Odoo
- `email` - Enviar email
- `sms` - Enviar SMS (futuro)
- `ai_response` - Respuesta con IA
- `human_takeover` - Pausar bot

### 5.2 Sistema de Variables

```
{{contact.name}}           - Nombre del contacto
{{contact.phone}}          - Teléfono
{{contact.email}}          - Email
{{contact.tags}}           - Etiquetas
{{contact.odoo_id}}        - ID en Odoo
{{contact.custom.*}}       - Campos personalizados

{{conversation.id}}        - ID conversación
{{conversation.channel}}   - Canal
{{conversation.agent}}     - Agente asignado
{{conversation.status}}    - Estado actual

{{message.text}}           - Texto del último mensaje
{{message.type}}           - Tipo de mensaje

{{system.date}}            - Fecha actual
{{system.time}}            - Hora actual
{{system.day_of_week}}     - Día de la semana
{{system.business_hours}}  - Si está en horario

{{odoo.partner.*}}         - Datos del partner
{{odoo.last_order.*}}      - Último pedido
{{odoo.balance}}           - Saldo del cliente
```

### 5.3 A/B Testing

- Distribución configurable entre variantes
- Métricas: tasa de respuesta, conversión, CSAT
- Auto-selección de ganador
- Duración por tiempo o número de contactos

---

## 6. Inbox y Gestión de Agentes

### 6.1 Sistema de Colas

- **Round-robin**: Distribuir equitativamente
- **Least-busy**: Al agente con menos conversaciones
- **Skill-based**: Según habilidades del agente
- **Sticky**: Mismo agente si contacto fue atendido antes
- **Priority**: VIPs primero, luego por tiempo

### 6.2 Configuración de Cola

- Nombre y descripción
- Método de asignación
- Máximo conversaciones por agente
- Re-asignación por timeout
- Horario de atención
- Flujo fuera de horario
- SLA primera respuesta
- SLA resolución

### 6.3 Estados de Agente

- 🟢 **Online** - Recibe nuevas conversaciones
- 🟡 **Ausente** - No recibe nuevas, mantiene activas
- 🔴 **Ocupado** - Atendiendo urgente
- 🍽️ **Almuerzo** - Pausa temporal
- 📞 **En llamada** - No recibe nuevas
- ⚫ **Offline** - Desconectado

### 6.4 Panel de Supervisor

- Estado de todos los agentes
- Conversaciones en cola
- SLA en tiempo real
- Conversaciones críticas (alerta)
- Métricas por agente
- Re-asignación manual
- Actividad en tiempo real

### 6.5 CSAT

- Encuesta después de resolución
- Escala 1-5 con emojis
- Pregunta de feedback si negativo
- Notificación a supervisor
- Métricas por agente/cola

---

## 7. Integración Odoo

### 7.1 Módulos Soportados

| Módulo | Modelo | Acciones |
|--------|--------|----------|
| Contactos | res.partner | Buscar, crear, actualizar, sincronizar |
| CRM | crm.lead | Crear lead, actualizar etapa, agregar nota |
| Ventas | sale.order | Consultar, crear cotización, confirmar, enviar PDF |
| Inventario | stock.* | Consultar stock, disponibilidad |
| Helpdesk | helpdesk.ticket | Crear ticket, estado, asignar |
| Facturación | account.move | Consultar, enviar PDF, estado pago |
| Calendario | calendar.event | Disponibilidad, crear cita |
| Productos | product.* | Buscar, detalles, precio |
| Envíos | stock.picking | Estado, tracking |

### 7.2 Nodos Odoo en Flow Builder

**Contactos:**
- `odoo_search_partner` - Buscar cliente
- `odoo_create_partner` - Crear cliente
- `odoo_update_partner` - Actualizar cliente

**CRM:**
- `odoo_create_lead` - Crear oportunidad
- `odoo_update_lead_stage` - Mover en pipeline
- `odoo_add_lead_note` - Agregar nota

**Ventas:**
- `odoo_search_orders` - Buscar pedidos
- `odoo_create_quotation` - Crear cotización
- `odoo_confirm_order` - Confirmar pedido
- `odoo_send_quotation_pdf` - Enviar PDF

**Inventario:**
- `odoo_check_stock` - Consultar disponibilidad
- `odoo_tracking_status` - Estado de envío

**Helpdesk:**
- `odoo_create_ticket` - Crear ticket
- `odoo_ticket_status` - Estado de ticket

**Productos:**
- `odoo_search_products` - Buscar productos
- `odoo_product_details` - Información detallada

**Facturación:**
- `odoo_check_balance` - Saldo del cliente
- `odoo_send_invoice_pdf` - Enviar factura

**Calendario:**
- `odoo_check_availability` - Disponibilidad
- `odoo_create_appointment` - Crear cita

### 7.3 Automatizaciones Odoo → WhatsApp

- Pedido confirmado → Mensaje de confirmación
- Pedido enviado → Mensaje con tracking
- Pago recibido → Agradecimiento
- Factura vencida → Recordatorio
- Recordatorio de cita → 24h antes
- Ticket resuelto → Encuesta satisfacción

### 7.4 Módulo Odoo

```
odoo_whatsapp_hub/
├── __manifest__.py
├── models/
│   ├── res_partner.py        # Campos WhatsApp en partner
│   ├── whatsapp_account.py
│   ├── whatsapp_conversation.py
│   └── whatsapp_message.py
├── controllers/
│   ├── webhook.py            # Eventos de WhatsApp Central
│   └── api.py
├── wizards/
│   ├── send_whatsapp.py      # Enviar mensaje
│   └── mass_whatsapp.py      # Envío masivo
├── views/
│   ├── res_partner_views.xml # Tab WhatsApp
│   └── whatsapp_*.xml
├── static/src/
│   ├── js/chat_widget.js     # Widget de chat
│   └── css/whatsapp.css
└── security/ir.model.access.csv
```

---

## 8. Autenticación y Roles

### 8.1 Roles

| Rol | Permisos |
|-----|----------|
| **Admin** | Todo acceso: config, flujos, usuarios, integraciones |
| **Supervisor** | Ver todas las conversaciones, reasignar, reportes equipo |
| **Agente** | Solo conversaciones asignadas, responder, transferir |

### 8.2 JWT

- Access token: 1 hora
- Refresh token: 7 días (httpOnly cookie)
- Permisos en payload

---

## 9. Docker Compose

```yaml
version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: whatsapp_central
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    ports:
      - "6379:6379"

  whatsapp-core:
    build: ./services/whatsapp-core
    environment:
      NODE_ENV: production
      API_GATEWAY_URL: http://api-gateway:8000
      REDIS_URL: redis://redis:6379
    volumes:
      - whatsapp_sessions:/app/sessions
    ports:
      - "3001:3001"

  api-gateway:
    build: ./services/api-gateway
    environment:
      DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/whatsapp_central
      REDIS_URL: redis://redis:6379
      JWT_SECRET: ${JWT_SECRET}
    ports:
      - "8000:8000"

  flow-engine:
    build: ./services/flow-engine
    environment:
      DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/whatsapp_central
      REDIS_URL: redis://redis:6379

  integrations:
    build: ./services/integrations
    environment:
      DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/whatsapp_central
      ODOO_URL: ${ODOO_URL}
      ODOO_DB: ${ODOO_DB}
      ODOO_USER: ${ODOO_USER}
      ODOO_PASSWORD: ${ODOO_PASSWORD}

  frontend:
    build: ./frontend
    ports:
      - "3000:80"

  nginx:
    image: nginx:alpine
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
    ports:
      - "80:80"
      - "443:443"

volumes:
  postgres_data:
  redis_data:
  whatsapp_sessions:
```

---

## 10. Roadmap de Implementación

### Fase 1: Fundación
- Estructura proyecto + Docker Compose
- whatsapp-core: Baileys, sesiones, multi-número
- api-gateway: Auth JWT, roles
- Frontend: Login, Dashboard, gestión números
- Inbox básico: Lista conversaciones, chat

### Fase 2: Flow Engine Básico
- Motor de ejecución de flujos
- Nodos básicos: mensaje, botones, wait_input, condición
- Sistema de variables
- Frontend: Flow Builder con React Flow
- Triggers: welcome, keyword, fallback

### Fase 3: Inbox Avanzado + Multi-agente
- Sistema de colas
- Asignación inteligente
- Transferencia bot → humano → bot
- Estados de agente
- Respuestas rápidas
- Notas internas
- Panel supervisor
- SLA tracking

### Fase 4: Flow Engine Avanzado
- Nodos avanzados: switch, loop, random, sub-flow
- Nodos validación
- Templates reutilizables
- Variables globales
- Nodo JavaScript
- A/B Testing
- Nodo AI Response

### Fase 5: Integración Odoo Completa
- Conexión XML-RPC
- Sincronización contactos
- Todos los nodos Odoo
- Eventos Odoo → WhatsApp
- Envío de PDFs

### Fase 6: Módulo Odoo
- Módulo odoo_whatsapp_hub
- Widget de chat en partner
- Historial conversaciones
- Enviar WhatsApp desde Odoo
- Acciones automáticas
- Envío masivo

### Fase 7: Reportes y Analytics
- Dashboard analytics
- Métricas por agente/cola/flujo
- CSAT
- Exportación
- Reportes programados

### Fase 8: Multi-canal (Futuro)
- Email (SMTP/IMAP)
- SMS (Twilio)
- Inbox unificado
- WhatsApp Business API oficial

---

## 11. Requisitos de Servidor

- **RAM**: 4GB mínimo, 8GB recomendado
- **CPU**: 2 cores mínimo
- **Disco**: SSD, 50GB+
- **SO**: Linux (Ubuntu 22.04 recomendado)
- **Docker**: 24.0+
- **Docker Compose**: 2.20+

---

## 12. Consideraciones de Seguridad

- Passwords con bcrypt (cost 12)
- JWT con refresh tokens en httpOnly cookies
- Rate limiting en auth
- HTTPS obligatorio (Let's Encrypt)
- Secrets en variables de entorno
- No commitear .env
- Backup automatizado de PostgreSQL y sesiones
- Futuro: 2FA para admins

---

*Documento generado durante sesión de brainstorming.*
*Aprobado para iniciar implementación.*