Files

Claude AI a92a7efccc Initial commit: Documentación completa del proyecto WhatsApp Centralizado

- README principal con descripción del proyecto
- Documento de diseño completo (arquitectura, DB, flujos)
- Documentación de API REST y WebSocket
- Guía del Flow Builder (30+ tipos de nodos)
- Documentación de integración con Odoo
- Guía de despliegue con Docker
- Esquema de base de datos
- Estructura de carpetas del proyecto
- Archivo .env.example con todas las variables

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

2026-01-29 09:29:57 +00:00

20 KiB

Raw Blame History

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

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

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.

20 KiB Raw Blame History