Agente de WhatsApp con IA que agenda turnos: arquitectura

Introducción

Casi todos los tutoriales de asistentes de IA se enfocan en prompts o modelos.

En producción, eso rara vez es lo difícil.

El desafío real es construir un sistema que:

• acepte varios formatos de entrada (texto y voz)
• entienda la intención
• valide restricciones reales (disponibilidad de calendario)
• ejecute acciones de forma segura
• mantenga el contexto de la conversación.

En este artículo desarmo la arquitectura completa de un agente de IA en WhatsApp que agenda turnos automáticamente.

En lugar de un tutorial paso a paso, esto es un recorrido práctico de ingeniería:

• arquitectura del sistema
• decisiones de diseño del workflow
• configuraciones reales de los nodos
• fragmentos de JSON del flow de producción.

Panorama del flow completo

Antes de meternos en detalles, esta es la arquitectura general:

WhatsApp (Twilio) → Webhook → Normalización → Ramificación audio/texto → Transcripción (si hace falta) → Agente de IA (tools + memoria) → Parser de salida → Respuesta

Principio clave:

El LLM es apenas un componente dentro de un sistema más grande.

Por qué la arquitectura importa más que el modelo

Un agente conversacional que agenda turnos tiene que respetar restricciones reales:

• los eventos del calendario representan tiempo ocupado
• los datos del negocio tienen que venir de fuentes estructuradas
• las conversaciones necesitan estado
• voz y texto tienen que comportarse igual desde la perspectiva del agente.

Sin resolver eso primero, el modelo se vuelve poco confiable por más bueno que sea.

Paso 1: entrada del webhook (Twilio → n8n)

Todos los mensajes entrantes llegan por webhook.

Configuración de ejemplo del nodo:

{
  "type": "n8n-nodes-base.webhook",
  "parameters": {
    "httpMethod": "POST",
    "path": "your-webhook-id"
  },
  "name": "Webhook"
}

Decisión de diseño:

Nunca dejes que los nodos de abajo dependan de la estructura cruda del webhook. Normalizá temprano.

Paso 2: normalización de datos

Convertimos el payload entrante en un formato interno estable:

• type (audio o texto)
• body
• from
• URL de la grabación

{
  "type": "n8n-nodes-base.set",
  "name": "Edit Fields",
  "parameters": {
    "assignments": {
      "assignments": [
        { "name": "type", "value": "={{ $json.body.MessageType }}" },
        { "name": "body", "value": "={{ $json.body.Body }}" },
        { "name": "from", "value": "={{ $json.body.From }}" },
        { "name": "recording", "value": "={{ $json.body.MediaUrl0 }}" }
      ]
    }
  }
}

Esto importa porque el resto del sistema queda independiente de los formatos propios de cada proveedor.

Paso 3: ramificar audio y texto

Los mensajes de audio requieren pasos extra:

• descargar la grabación
• speech-to-text
• volver a unir en el pipeline unificado.

Lógica de ejemplo del switch:

{
  "type": "n8n-nodes-base.switch",
  "name": "Switch",
  "parameters": {
    "rules": {
      "values": [
        { "outputKey": "Audio", "conditions": [{ "leftValue": "={{ $json.type }}", "rightValue": "audio" }] },
        { "outputKey": "Text", "conditions": [{ "leftValue": "={{ $json.type }}", "rightValue": "text" }] }
      ]
    }
  }
}

Principio importante:

El agente de IA nunca debería saber si la entrada fue audio o texto.

Paso 4: procesar el audio (descargar + transcribir)

Los audios se traen de los servidores de Twilio y se transcriben con OpenAI.

{
 "type": "n8n-nodes-base.httpRequest",
 "name": "HTTP Request",
 "parameters": {
   "url": "={{ $json.recording }}",
   "authentication": "predefinedCredentialType",
   "nodeCredentialType": "twilioApi"
 }
}

{
  "type": "@n8n/n8n-nodes-langchain.openAi",
  "name": "Transcribe a recording",
  "parameters": {
    "resource": "audio",
    "operation": "transcribe",
    "options": { "language": "es" }
  }
}

Idea clave:

Normalizá las entradas ANTES de que lleguen al agente. Si no, los prompts se complican sin necesidad.

Paso 5: unificación de la entrada (nodo crítico)

Las dos ramas convergen en una sola estructura estandarizada:

const base = { ...$('Edit Fields').first().json };

const normalizedBody = (base.type === 'audio')
  ? ($input.first().json.text ?? '').trim()
  : (base.body ?? '');

return [{
  json: {
    ...base,
    body: normalizedBody,
    from: base.from.split('whatsapp:')[1]
  }
}];

Eso reduce muchísimo la complejidad río abajo.

Paso 6: el detalle de UX que casi nadie muestra

Antes de generar la respuesta, mandamos un indicador de "escribiendo" por Twilio con un nodo HTTP Request.

{
 "type": "n8n-nodes-base.httpRequest",
 "name": "Señal de escribiendo respuesta",
 "parameters": {
   "method": "POST",
   "url": "https://messaging.twilio.com/v2/Indicators/Typing.json",
   "bodyParameters": {
     "parameters": [
       { "name": "messageId", "value": "={{ $('Webhook').item.json.body.MessageSid }}" },
       { "name": "channel", "value": "whatsapp" }
     ]
   }
 }
}

Cambio chico, salto grande en inteligencia percibida. El usuario siente que interactúa con un sistema real y no con una automatización.

Paso 7: el agente de IA (donde, para mí, la mayoría simplifica de más)

El agente se compone de:

Modelo

GPT-4.1-mini con esquema de salida estructurada. Uso un modelo mini porque escala bien en ahorro, sin gastar tiempo pensando sobre información que ya tiene.

Memoria

Sesión indexada por número de teléfono.

Ventana limitada a las últimas interacciones para que no crezca sin control.

Tools

• Contexto de la empresa (Google Sheets)
• Consulta de disponibilidad en el calendario
• Creación de eventos en el calendario.

Regla de diseño clave:

El modelo no inventa datos. Consulta tools.

Configuración de ejemplo del modelo

{
  "model": "gpt-4.1-mini",
  "response_format": "json_schema"
}

La salida estructurada evita fallas río abajo.

Paso 8: lógica de validación de disponibilidad

Una restricción fundamental:

Los eventos del calendario representan tiempo ocupado, no disponibilidad.

El sistema tiene que:

• traer los eventos
• calcular los huecos libres
• proponer solo horarios válidos.

Esa sola regla evita la mayoría de las fallas reales de agendamiento.

Paso 9: parseo defensivo de la salida

Los agentes no siempre devuelven la misma estructura de salida.

En lugar de confiar ciegamente en la respuesta, parseamos a la defensiva:

function tryParseJson(output) {
  try { return JSON.parse(output); } catch { return null; }
}

Los sistemas de producción asumen variabilidad.

Paso 10: mandar la respuesta por WhatsApp

El nodo final devuelve el mensaje generado por la IA usando Twilio. Simple, pero recién después de las capas de validación y formato.

{
 "type": "n8n-nodes-base.twilio",
 "name": "Send an SMS/MMS/WhatsApp message",
 "parameters": {
   "toWhatsapp": true,
   "to": "={{ $('Normalizar datos').item.json.from }}",
   "message": "={{ $json.message }}"
 }
}

Lecciones aprendidas

1. Los asistentes de IA son problemas de arquitectura más que de IA.
2. El diseño de las tools importa más que el prompt engineering.
3. Normalizar la entrada reduce muchísimo la complejidad.
4. El diseño de la memoria define la confiabilidad.
5. Detalles de UX como el indicador de escritura aumentan la confianza.

Conclusión

Los agentes de IA no son chatbots con mejores prompts.

Son sistemas compuestos por:

• entradas estructuradas
• razonamiento guiado por tools
• ejecución acotada.

Si estás armando algo parecido y querés ayuda para pasar de prototipo a producción, escribime.