Agente IA para WhatsApp: guia de configuracion paso a paso

Para crear un agente IA para WhatsApp necesitas tres componentes: una API de mensajeria (Evolution API o Meta Cloud API), un motor de orquestacion (n8n) y un modelo de lenguaje (GPT-4o-mini, Claude o Gemini). Esta guia muestra el setup exacto que usamos en AgentesNexo para clientes con 50 a 300 conversaciones diarias.

Un restaurante con 80 reservas diarias via WhatsApp puede atender cada consulta en menos de 3 segundos, 24 horas al dia, sin operador humano. Un e-commerce con 200 consultas de producto puede calificar leads y enviar cotizaciones de forma automatica. Esto no es teoria: es lo que corre en produccion.

Que necesitas antes de empezar

• Numero de WhatsApp dedicado (nunca el numero personal del negocio)
• Servidor o VPS con Docker (minimo 2 vCPU, 2GB RAM)
• Instancia de n8n (self-hosted o cloud)
• API key de OpenAI, Anthropic o Google
• 2 a 4 horas para el setup completo

Paso 1: Instalar Evolution API

Evolution API v2 es el puente que conecta WhatsApp con tu backend via WebSocket. Es open source, estable en produccion y soporta multiples instancias (un servidor, varios numeros).

# docker-compose.yml minimo
version: '3.8'
services:
  evolution-api:
    image: atendai/evolution-api:v2.2.3
    ports:
      - #43a047">"8080:8080"
    environment:
      - SERVER_URL=https://tu-dominio.com
      - AUTHENTICATION_API_KEY=tu-api-key-secreta
      - DATABASE_PROVIDER=postgresql
      - DATABASE_CONNECTION_URI=postgresql://user:pass@db:5432/evolution
    volumes:
      - evolution_instances:/evolution/instances

Una vez corriendo, creas la instancia y escaneas el QR con el numero dedicado:

curl -X POST https://tu-dominio.com/instance/create \
  -H #43a047">"apikey: tu-api-key-secreta" \
  -H #43a047">"Content-Type: application/json" \
  -d '{#43a047">"instanceName": "mi-negocio", "integration": "WHATSAPP-BAILEYS"}'

La API te devuelve un QR en base64. Lo escaneas desde WhatsApp en el celular con el numero dedicado. Conexion lista.

Paso 2: Conectar n8n via Webhook

Evolution API envia cada mensaje entrante a un webhook configurable. En n8n construyes el flujo que lo recibe y procesa:

1. Nodo Webhook — metodo POST, path /whatsapp/incoming
2. Nodo IF — filtra solo mensajes de texto: body.data.messageType === "conversation"
3. Nodo Code — extrae numero y texto del payload:

const phone = $input.first().json.data.key.remoteJid.replace('@s.whatsapp.net', '');
const message = $input.first().json.data.message.conversation;
const timestamp = $input.first().json.data.messageTimestamp;

return [{ phone, message, timestamp }];

Registra el webhook en Evolution para que empiece a enviar eventos:

curl -X POST https://tu-dominio.com/webhook/set/mi-negocio \
  -H #43a047">"apikey: tu-api-key-secreta" \
  -H #43a047">"Content-Type: application/json" \
  -d '{#43a047">"url": "https://tu-n8n.com/webhook/whatsapp/incoming", "events": ["MESSAGES_UPSERT"]}'

Paso 3: Memoria de conversacion con PostgreSQL

El agente IA necesita recordar lo que el usuario dijo antes. Sin memoria, cada mensaje parece una conversacion nueva. La solucion mas robusta: guardar el historial en PostgreSQL.

CREATE TABLE conversation_history (
  id SERIAL PRIMARY KEY,
  phone VARCHAR(20),
  role VARCHAR(10),
  content TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_phone_created ON conversation_history (phone, created_at DESC);

En n8n, antes de llamar al modelo, recuperas los ultimos 10 mensajes del numero:

SELECT role, content
FROM conversation_history
WHERE phone = '{{ $json.phone }}'
ORDER BY created_at DESC
LIMIT 10;

Esto le da al agente contexto completo: sabe si el usuario ya pregunto el precio, si ya dio su nombre, si esta comparando opciones con la competencia.

Paso 4: Configurar el agente IA

El nodo de n8n que llama al modelo recibe el historial como contexto. El system prompt define la personalidad y los limites del agente:

const systemPrompt = #43a047">`Eres el asistente de [Tu Negocio].
Funcion: responder consultas, calificar leads y agendar citas.
Cuando el usuario quiera agendar: pide nombre, servicio y horario preferido.
Horarios disponibles: lunes a sabado 9am a 6pm.
Responde siempre en espanol. Maximo 3 oraciones por respuesta.
Si no sabes algo, di que un asesor se comunicara pronto.`;

Usa GPT-4o-mini o Gemini 2.0 Flash para el 90% de los casos: cuestan 10 veces menos que los modelos grandes y responden igual de bien para consultas de ventas estandar.

La respuesta del modelo se envia de regreso al usuario via Evolution:

curl -X POST https://tu-dominio.com/message/sendText/mi-negocio \
  -H #43a047">"apikey: tu-api-key-secreta" \
  -H #43a047">"Content-Type: application/json" \
  -d '{#43a047">"number": "591XXXXXXXX@s.whatsapp.net", "text": "Respuesta generada por IA"}'

Arquitectura del sistema

El flujo completo de un mensaje entrante:

Usuario envia mensaje en WhatsApp
  → Evolution API captura el evento (WebSocket)
    → n8n Webhook recibe el payload
      → Filtro: solo mensajes de texto
        → PostgreSQL: recupera historial del numero
          → Modelo IA: genera respuesta con contexto
            → PostgreSQL: guarda mensaje + respuesta
              → Evolution API: envia respuesta
                → Usuario recibe respuesta en WhatsApp

Tiempo de respuesta tipico: 2 a 4 segundos. Costo por conversacion de 10 mensajes: aproximadamente $0.02 USD con GPT-4o-mini.

Lo que aprendimos implementando esto en produccion

• Nunca uses tu numero principal: WhatsApp detecta patrones automatizados y puede suspender el numero. Usa un numero dedicado y respeta el limite de 20 mensajes por minuto.
• El system prompt vale mas que el modelo: Un prompt especifico para el negocio con GPT-4o-mini supera a un prompt generico con GPT-4o. Dedica tiempo a afinarlo.
• Guarda cada mensaje en tiempo real: Los mensajes de WhatsApp no tienen API de historial. Si la instancia se desconecta, perdes el contexto. Persiste en PostgreSQL antes de procesar.
• Filtra los mensajes de media desde el inicio: Evolution envia eventos por audios, imagenes y stickers. Sin filtro, tu agente intentara procesar contenido que no puede manejar. Define un fallback claro.
• Monitorea la conexion de la instancia: Las instancias de Baileys se desconectan ocasionalmente. Configura un cron que verifique el estado cada 5 minutos y reconecte si es necesario.

En resumen

1. Evolution API v2: conecta tu numero de WhatsApp al sistema via WebSocket
2. n8n: orquesta el flujo completo (webhook → filtro → IA → respuesta)
3. PostgreSQL: persiste el historial de cada conversacion por numero
4. Modelo IA: GPT-4o-mini o Gemini Flash para respuestas rapidas y economicas
5. System prompt especifico: define exactamente que puede y que no puede hacer el agente
6. Numero dedicado: separado del numero personal, preparado para volumen alto

Si quieres implementar esto en tu negocio sin construirlo desde cero, en AgentesNexo lo hacemos por ti. Escríbenos en agentesnexo.com o por WhatsApp al +591 67564218