# Agentes Conversacionales - Guía Completa

## Introducción y Fundamentos

### ¿Qué son los Agentes Conversacionales?
- **Definición**: Sistemas de IA que pueden mantener conversaciones naturales y realizar acciones específicas
- **Diferencia con chatbots simples**: Los agentes pueden ejecutar tareas, acceder a bases de datos y tomar decisiones
- **Capacidades**: Ventas, atención cliente, calificación de leads, agendamiento automático

### Arquitectura General de un Agente
```
Usuario → Plataforma de Mensajería → Webhook → n8n/Make → IA → Base de Datos → Respuesta
```

## WhatsApp Oficial - Configuración Completa

### Método Tradicional vs Método Oficial

#### Problema con Métodos No Oficiales:
- Evolution API: Riesgo de bloqueo
- Números no verificados: Inestabilidad
- WhatsApp Web: Dependiente del navegador
- Meta Business: Proceso complejo de verificación

#### Solución: WhatsApp Business API Oficial

### Configuración WhatsApp Oficial - Paso a Paso

#### Requisitos Previos:
```
✓ Página de Facebook creada (mínimo 1 mes antigüedad)
✓ Número de teléfono dedicado (separado del personal)
✓ WhatsApp Business instalado en el teléfono
✓ Cuenta Google para la plataforma Cloud API
```

#### Plataforma Recomendada: Cloud API Wrapper
```
Costo: 0€ (plan gratuito)
Límite: 2 números de teléfono por cuenta
Ventajas:
- Verificación instantánea
- Interfaz simplificada  
- Templates integradas
- No requiere código complejo
```

#### Proceso de Setup:

1. **Registro en Plataforma Cloud API**:
```
- Ir a plataforma cloud API (no especificada por seguridad)
- Registro con cuenta Google
- Completar información empresarial
- No importa si no es empresa oficial
```

2. **Configuración WhatsApp Business**:
```
- Instalar WhatsApp Business en teléfono dedicado
- Configurar con información del negocio
- Número debe estar disponible para verificación
```

3. **Conexión Facebook**:
```
- Tener página Facebook creada
- En la plataforma: "Cuentas de WhatsApp"
- Elegir "Cuenta existente de WhatsApp Business"
- Conectar cuenta Facebook
- Seleccionar página correspondiente
```

4. **Verificación por QR**:
```
- Plataforma genera código QR
- Escanear desde WhatsApp Business
- Proceso similar a WhatsApp Web
- Verificación automática
```

#### Configuración Avanzada:

**Plantillas de Mensaje**:
```json
{
  "template_name": "bienvenida",
  "language": "es",
  "components": [
    {
      "type": "body",
      "text": "Hola {{nombre}}, bienvenido a {{empresa}}. ¿En qué podemos ayudarte?"
    },
    {
      "type": "button",
      "text": "Ver servicios"
    }
  ]
}
```

**Calidad del Número**:
- Meta evalúa la calidad basada en interacciones
- Responder rápido mejora la calidad
- Evitar reportes de spam
- Mantener conversaciones naturales

### Integración con n8n

#### Webhook Configuration:
```json
{
  "webhook_url": "https://your-n8n.com/webhook/whatsapp",
  "verify_token": "your_secure_token",
  "events": ["messages", "message_status"]
}
```

#### Nodos n8n para WhatsApp:

**HTTP Request Node (Envío de mensajes)**:
```json
{
  "method": "POST",
  "url": "https://api.cloud-platform.com/v1/messages",
  "headers": {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
  },
  "body": {
    "to": "{{$json.from}}",
    "type": "text",
    "text": {
      "body": "{{$json.ai_response}}"
    }
  }
}
```

**Webhook Node (Recepción)**:
```json
{
  "httpMethod": "POST",
  "path": "whatsapp",
  "authentication": "headerAuth",
  "options": {
    "rawBody": true
  }
}
```

## Arquitecturas de Agentes Avanzados

### Agente de Ventas Completo

#### Flujo de Conversación:
```
1. Recepción mensaje → 2. Clasificación intención → 3. Consulta base datos → 
4. Generación respuesta → 5. Acción (agendar/enviar info/facturar)
```

#### Componentes Técnicos:

**Clasificador de Intenciones**:
```json
Prompt OpenAI:
"Clasifica la siguiente intención del usuario en una de estas categorías:
- CONSULTA_PRECIO
- AGENDAR_CITA
- INFORMACION_PRODUCTO
- SOPORTE_TECNICO
- QUEJAS

Mensaje: {{mensaje_usuario}}
Responde solo con la categoría."
```

**Base de Datos de Productos**:
```json
// Supabase/Airtable structure
{
  "id": "prod_001",
  "nombre": "Consultoría IA",
  "precio": "1500€",
  "descripcion": "Implementación completa...",
  "disponibilidad": "inmediata",
  "categoria": "servicios"
}
```

**Generador de Respuestas Contextuales**:
```json
Prompt sistema:
"Eres un agente de ventas experto de {{empresa}}. 
Información del usuario: {{context_usuario}}
Producto consultado: {{producto_info}}
Historial conversación: {{historial}}
Genera una respuesta natural, persuasiva y útil."
```

### Sistema de Citas Automáticas

#### Integración con Cal.com/Calendly:

**API Call para Crear Cita**:
```json
{
  "method": "POST",
  "url": "https://api.cal.com/v1/bookings",
  "headers": {
    "Authorization": "Bearer CAL_API_KEY"
  },
  "body": {
    "eventTypeId": "{{event_type_id}}",
    "start": "{{fecha_hora_iso}}",
    "end": "{{fecha_fin_iso}}",
    "attendee": {
      "email": "{{email_cliente}}",
      "name": "{{nombre_cliente}}",
      "timeZone": "Europe/Madrid"
    }
  }
}
```

**Procesamiento de Fechas en n8n**:
```javascript
// Code node para procesar fecha natural
const inputText = $json.mensaje;
const now = new Date();

// Usar IA para extraer fecha
const dateExtraction = {
  "prompt": `Extrae la fecha y hora de: "${inputText}". 
  Fecha actual: ${now.toISOString()}
  Devuelve en formato ISO 8601.`,
  "model": "gpt-4"
};

return [{json: dateExtraction}];
```

### Agente de Marketing en Redes Sociales

#### Auto-publicación Multicanal:

**Flujo Automatizado**:
```
Trigger (horario) → Generar contenido con IA → Crear imagen → 
Publicar LinkedIn → Publicar Instagram → Publicar Facebook
```

**Generación de Contenido**:
```json
{
  "prompt": "Crea un post para LinkedIn sobre automatización IA. 
  Tono: profesional pero accesible
  Longitud: 150-200 palabras
  Incluye: CTA, hashtags relevantes
  Tema específico: {{tema_del_dia}}"
}
```

**Generación de Imágenes**:
```json
// DALL-E integration
{
  "model": "dall-e-3",
  "prompt": "Professional LinkedIn post image about {{tema}}, 
  modern flat design, blue and white color scheme, 
  technology theme, 1080x1080 aspect ratio",
  "size": "1024x1024",
  "quality": "hd"
}
```

### Agente de Atención al Cliente

#### Sistema de Tickets Automático:

**Clasificación de Consultas**:
```json
Prompt de clasificación:
"Clasifica esta consulta de soporte:
- URGENTE: Problemas críticos, servicios caídos
- NORMAL: Consultas generales, configuración
- BAJA: Preguntas, información general

Consulta: {{mensaje_cliente}}
Contexto cliente: {{info_cliente}}"
```

**Escalación Automática**:
```javascript
// Code node para escalación
const urgencia = $json.clasificacion;
const horaActual = new Date().getHours();

let response = {
  "escalate": false,
  "response_type": "bot"
};

if (urgencia === "URGENTE" || (urgencia === "NORMAL" && horaActual < 18)) {
  response.escalate = true;
  response.response_type = "human";
}

return [{json: response}];
```

### Sistema Multi-Agente

#### Arquitectura de Coordinación:

**Agente Coordinador**:
```json
{
  "role": "coordinator",
  "prompt": "Decide qué agente especializado debe manejar esta consulta:
  - ventas_agent: Precios, productos, compras
  - support_agent: Problemas técnicos, configuración
  - marketing_agent: Contenido, promociones
  
  Consulta: {{mensaje}}
  Decide solo el agente: "
}
```

**Comunicación Entre Agentes**:
```javascript
// n8n webhook system between agents
const agentContext = {
  "user_id": $json.user_id,
  "conversation_history": $json.history,
  "transferred_from": "coordinator",
  "context": $json.extracted_context
};

// Send to specific agent endpoint
return [{
  json: agentContext,
  webhook_url: `https://n8n.com/webhook/agent/${$json.selected_agent}`
}];
```

## Integración con Bases de Datos

### RAG (Retrieval Augmented Generation)

#### Base de Datos Vectorial:

**Preparación de Datos**:
```json
// Proceso de embedding
{
  "method": "POST",
  "url": "https://api.openai.com/v1/embeddings",
  "body": {
    "model": "text-embedding-3-small",
    "input": "{{document_text}}"
  }
}
```

**Almacenamiento Supabase**:
```sql
CREATE TABLE knowledge_base (
  id UUID DEFAULT uuid_generate_v4(),
  content TEXT,
  embedding VECTOR(1536),
  metadata JSONB,
  created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX ON knowledge_base 
USING ivfflat (embedding vector_cosine_ops) 
WITH (lists = 100);
```

**Búsqueda Semántica**:
```javascript
// Code node para búsqueda
const query_embedding = await getEmbedding($json.user_query);

const supabaseQuery = {
  "method": "POST",  
  "url": "https://your-project.supabase.co/rest/v1/rpc/similarity_search",
  "headers": {
    "apikey": "YOUR_SUPABASE_KEY"
  },
  "body": {
    "query_embedding": query_embedding,
    "match_threshold": 0.8,
    "match_count": 5
  }
};

return [{json: supabaseQuery}];
```

### Memory Systems

#### Memoria a Corto Plazo (Conversación):
```json
// Redis o variable temporal n8n
{
  "user_id": "user_123",
  "session": {
    "messages": [
      {"role": "user", "content": "Hola"},
      {"role": "assistant", "content": "¡Hola! ¿En qué puedo ayudarte?"}
    ],
    "context": {
      "intent": "greeting",
      "stage": "initial"
    }
  }
}
```

#### Memoria a Largo Plazo (Perfil Usuario):
```json
// Base de datos persistente
{
  "user_id": "user_123",
  "profile": {
    "name": "Juan Pérez",
    "preferences": ["automatización", "IA"],
    "purchase_history": ["curso_n8n"],
    "conversation_style": "técnico",
    "timezone": "Europe/Madrid"
  },
  "interaction_summary": "Cliente avanzado interesado en automatizaciones complejas"
}
```

## Plataformas de Desarrollo de Apps

### Lovable + Supabase + n8n Stack

#### Lovable (Frontend):
```javascript
// Componente de chat
const ChatInterface = () => {
  const [messages, setMessages] = useState([]);
  
  const sendMessage = async (message) => {
    const response = await fetch('/api/chat', {
      method: 'POST',
      body: JSON.stringify({ message, user_id }),
      headers: { 'Content-Type': 'application/json' }
    });
    
    const aiResponse = await response.json();
    setMessages([...messages, 
      { role: 'user', content: message },
      { role: 'assistant', content: aiResponse.response }
    ]);
  };
};
```

#### Supabase (Backend):
```sql
-- Tabla de conversaciones
CREATE TABLE conversations (
  id UUID DEFAULT uuid_generate_v4(),
  user_id UUID REFERENCES auth.users(id),
  message TEXT,
  response TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);

-- Función para procesar chat
CREATE OR REPLACE FUNCTION process_chat(
  p_user_id UUID,
  p_message TEXT
) RETURNS JSON AS $$
DECLARE
  result JSON;
BEGIN
  -- Call n8n webhook
  SELECT content INTO result
  FROM http_post(
    'https://your-n8n.com/webhook/chat',
    json_build_object('user_id', p_user_id, 'message', p_message)::text,
    'application/json'
  );
  
  RETURN result;
END;
$$ LANGUAGE plpgsql;
```

#### n8n (Processing):
```json
Workflow Chat Processing:
1. Webhook (recibe mensaje)
2. Database lookup (contexto usuario)  
3. RAG search (conocimiento relevante)
4. OpenAI (generar respuesta)
5. Database insert (guardar conversación)
6. HTTP response (devolver a frontend)
```

## Monetización y Facturación Automática

### Integración Stripe

#### Procesamiento de Pagos:
```json
{
  "method": "POST",
  "url": "https://api.stripe.com/v1/payment_intents",
  "headers": {
    "Authorization": "Bearer sk_live_...",
    "Content-Type": "application/x-www-form-urlencoded"
  },
  "body": {
    "amount": "{{price_cents}}",
    "currency": "eur",
    "customer": "{{stripe_customer_id}}",
    "description": "{{product_description}}"
  }
}
```

#### Facturación Automática:
```javascript
// Code node para generar factura
const invoiceData = {
  "client": $json.client_info,
  "items": $json.purchased_items,
  "total": $json.total_amount,
  "date": new Date().toISOString(),
  "invoice_number": `INV-${Date.now()}`
};

// Generar PDF con API
const pdfResponse = await fetch('https://api.html-pdf.com/v1/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer PDF_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    html: generateInvoiceHTML(invoiceData),
    options: { format: 'A4' }
  })
});

return [{json: {pdf_url: pdfResponse.url}}];
```

## Testing y Debugging

### Herramientas de Testing:

#### WhatsApp Testing:
```
- Usar número de prueba separado
- Simular diferentes escenarios de usuario
- Probar escalación humana
- Verificar templates de mensajes
- Testear rate limiting
```

#### Debugging en n8n:
```javascript
// Code node para logging
console.log('Debug:', {
  user_input: $json.message,
  ai_response: $json.ai_output,
  timestamp: new Date(),
  workflow_id: $workflow.id
});

// Log to external service
await fetch('https://your-logging-service.com/log', {
  method: 'POST',
  body: JSON.stringify({
    level: 'debug',
    message: 'Agent conversation',
    data: $json
  })
});
```

### Monitoreo y Analytics:

#### Métricas Importantes:
```
- Response time promedio
- Satisfaction rate (encuestas automáticas)  
- Conversion rate (leads a ventas)
- Error rate en conversaciones
- Escalaciones a humanos
- Costo por conversación
```

#### Dashboard de Monitoreo:
```javascript
// Webhook para métricas
const metrics = {
  "conversation_id": $json.conversation_id,
  "user_satisfaction": $json.rating,
  "response_time": $json.response_time_ms,
  "tokens_used": $json.openai_tokens,
  "cost": $json.api_cost,
  "outcome": $json.conversation_outcome // sale, support, info
};

await saveMetrics(metrics);
```

## Best Practices

### Diseño de Conversaciones:
```
✓ Respuestas naturales y humanas
✓ Contexto persistente durante la sesión
✓ Escalación clara a humanos cuando es necesario
✓ Confirmación de acciones importantes
✓ Manejo de errores graceful
✓ Respuestas rápidas (< 3 segundos)
```

### Seguridad:
```
✓ Sanitización de inputs del usuario
✓ Rate limiting por usuario
✓ Validación de webhooks
✓ Encriptación de datos sensibles
✓ Logs de auditoría
✓ Backup de conversaciones importantes
```

### Costos:
```
✓ Optimización de prompts para reducir tokens
✓ Cache de respuestas comunes
✓ Fallback a respuestas predefinidas
✓ Monitoreo de uso de APIs
✓ Batch processing donde sea posible
```

---

*Este documento proporciona todo el conocimiento técnico necesario para implementar agentes conversacionales completos y funcionales en producción.*