Agente de WhatsApp con Claude y Twilio, paso a paso

Introducción

Cada minuto que tu negocio tarda en responder un mensaje de WhatsApp es un minuto en el que el lead sigue hablando con otro. La respuesta típica es "contratá a alguien para cubrir" o "comprá una plataforma de chatbots". Ninguna de las dos escala como querés. Lo que armé es un agente que corre 24/7, responde con el tono del negocio, y pasa a una persona apenas aparece un lead que vale la atención.

El stack: Claude API para generar las respuestas, Twilio para el canal de WhatsApp, FastAPI con Python en el backend. SQLite para persistir la conversación, y NGrok para el túnel local durante el desarrollo. El build lo orquestó casi entero Claude Code, con un servidor MCP de Twilio para que el modelo tuviera documentación en vivo, y no datos de entrenamiento viejos.

Este post recorre cómo está diseñado el sistema, qué decisiones vale entender, y qué me sorprendió en el camino.

Por qué la Claude API no es lo mismo que una suscripción a Claude

Esto es lo que agarra a la gente desprevenida, así que conviene decirlo de entrada.

Cuando te suscribís a Claude, tenés acceso a Claude.ai, Claude Code y el workbench. Nada de eso te da acceso a la API para integraciones programáticas. Si estás armando un sistema que llama a Claude desde código, eso se factura aparte contra la API de Anthropic. O sea que tenés que crear API keys en platform.anthropic.com, cargar créditos ahí y, si querés, activar la recarga automática. Tu suscripción mensual y tu uso de API son dos ítems separados.

Para un agente de WhatsApp con volumen moderado, el costo de API no es prohibitivo. Pero si diseñás un sistema que manda los últimos 50 mensajes como contexto en cada mensaje entrante, sin pensar en la cuenta de tokens, lo vas a sentir.

Arquitectura del sistema

El flujo es así:

1. Un mensaje de WhatsApp llega al número de Twilio registrado como sender
2. Twilio reenvía el payload por webhook a una URL pública (túnel de NGrok en dev, URL del server en producción)
3. El backend FastAPI recibe el request y valida la firma de Twilio antes de hacer cualquier otra cosa
4. Si la validación pasa, el mensaje se escribe en SQLite, ligado a la conversación por número de teléfono
5. Corre un chequeo de modo: si la conversación está en modo "agent", se llama a la Claude API con los últimos N mensajes como contexto; si está en modo "human", no pasa nada automático
6. La respuesta sale de vuelta por Twilio hacia WhatsApp
7. El dashboard del operador consulta mensajes nuevos cada pocos segundos y le permite mandar mensajes manuales o cambiar el modo

El paso de validación de firma importa más de lo que parece. Twilio firma cada webhook saliente con un hash derivado de tu auth token y la URL del request. Validar esa firma antes de procesar nada significa que un POST malicioso a tu endpoint se lleva un 403 y nada más. Sin ese chequeo, tu endpoint es una superficie de ejecución abierta.

Memoria de conversación y ventana de contexto

SQLite con dos tablas: conversations, indexada por número de teléfono, y messages, que pertenecen a una conversación. Se guarda cada mensaje entrante y saliente.

Cuando Claude tiene que responder, el sistema trae los últimos N mensajes de esa conversación y los manda como contexto. El valor de N es una decisión con trade-offs reales de costo y calidad. Muy bajo (5 mensajes) y el agente pierde el hilo a mitad de la conversación. Muy alto (50+ mensajes) y quemás tokens en contexto mayormente irrelevante, y le sumás latencia a cada respuesta.

Para un caso típico de FAQ y calificación de leads, 10 a 15 mensajes es un punto de partida razonable. Después lo ajustás según los patrones reales que veas en producción.

El modelo human-in-the-loop

Esta es la pieza que hace al sistema realmente usable para un negocio, en vez de solo interesante como demo.

Cada conversación tiene un modo: agent o human. En modo agent, Claude maneja todas las respuestas. En modo human, Claude se queda callado y el operador responde a mano desde el dashboard. El operador puede cambiar el modo cuando quiera desde la interfaz.

El caso práctico: tu agente maneja del 80 al 90% del volumen entrante, que es gente preguntando las mismas 15 cosas sobre horarios, precios, disponibilidad y ubicación. Cuando alguien da señales de ser un lead que vale una conversación real, pasás la conversación a modo human y tomás vos. El lead nunca supo que hablaba con una IA, y no hace falta que lo sepa.

Algo con lo que me choqué en las pruebas: Claude respondió un par de veces "no tengo información sobre eso" antes de que yo cargara bien el contexto de la empresa. Después de cargarlo y reiniciar el server, esos mensajes seguían en el historial. Claude los tomaba como contexto y reforzaba la idea de que no tenía la información. La solución fue borrar esos mensajes de la base antes de volver a probar. En producción conviene pensar cómo manejar las correcciones de contexto con elegancia, en vez de borrar registros.

Contexto de la empresa y estructura del prompt

El contexto de la empresa vive en un archivo aparte que se carga en el system prompt. Tiene campos para: identidad y tono del negocio, horarios, productos o servicios, políticas y una sección de FAQ.

Acá es donde falla la mayoría de las implementaciones. Si el contexto es muy vago ("somos una empresa profesional que ofrece un gran servicio"), el agente alucina detalles para llenar los huecos. Si el contexto es muy largo y desordenado, el modelo entierra los datos importantes. La versión que implementé le da al agente un fallback explícito: si no sabe la respuesta, ofrece conectar con una persona en vez de adivinar.

El campo de tono importa más de lo que suena. "Profesional y formal" produce respuestas rígidas. "Directo, cálido y conciso" produce algo que se lee como una persona. El agente lo capta y se nota en los mensajes reales.

Claude Code como orquestador del build

Todo el backend lo generó Claude Code con dos archivos clave. CLAUDE.md define el stack, la arquitectura, el modelo de datos, los endpoints y la lógica de validación. PROMPT.md define la secuencia de build y le dice al modelo exactamente qué producir y en qué orden.

El servidor MCP de Twilio es lo que hace que esto funcione limpio. En vez de que Claude Code razone con el conocimiento de Twilio que tuviera en su entrenamiento, tiene conexión en vivo a la documentación. Cuando necesita saber cómo configurar un webhook de WhatsApp o cómo autenticar un messaging service, consulta el MCP y obtiene información actual. El código generado refleja la API real, no una versión de hace 18 meses.

La salida fue una aplicación FastAPI funcionando, con esquema SQLite, un middleware de validación de firma, un sistema de modos de conversación y un dashboard HTML para el operador. El archivo .env se generó vacío, que es lo correcto: el modelo creó la estructura y dejó los secretos para que los complete una persona.

No todo funcionó en la primera corrida. El contexto de la empresa no se cargaba bien después de reiniciar el server. Lo debuggeé con Claude Code en la misma sesión y encontró el problema. Ese ida y vuelta con el modelo para arreglar su propia salida es parte real del flujo, no es un build de un solo tiro.

Qué tenés que configurar vos

Claude Code se ocupa del código. Las partes que requieren configuración humana son:

• Crear la cuenta de Twilio y cargar el crédito inicial
• Registrar el sender de WhatsApp (vinculando un perfil de Meta Business existente, o comprando un número de Twilio y pasando por la verificación de Meta)
• Crear la cuenta de NGrok y configurar el dominio
• Crear la cuenta de la API de Anthropic y cargar crédito
• Completar el .env con las credenciales reales: Anthropic API key, Twilio account SID, Twilio auth token, dominio y token de NGrok, número from de WhatsApp, Messaging Service SID y WhatsApp Sender ID

El Messaging Service SID y el WhatsApp Sender ID son los que a todos se les pasan. El Messaging Service SID está en Messaging > Services en la consola de Twilio. El Sender ID aparece en la URL cuando abrís el detalle del sender, en Numbers and Senders > WhatsApp.

Trade-offs que conviene saber antes de desplegar

SQLite frente a otras bases: SQLite está bien para desarrollo y para producción de bajo volumen, digamos menos de unos cientos de conversaciones por día. Si vas a meter volumen, querés PostgreSQL e índices decentes en la búsqueda por número. SQLite se convierte en cuello de botella con escrituras concurrentes.

NGrok en producción: los túneles de NGrok son para desarrollo local. Cuando esto va a un server real, reemplazás la URL de NGrok en la configuración del webhook de Twilio por la URL real del server. Si te quedás en el plan gratis de NGrok, el dominio cambia al reiniciar y te rompe la config.

Elegir el modelo de Claude: el archivo PROMPT.md especifica qué modelo usar para generar respuestas. Haiku es rápido y barato, bueno para responder FAQ. Sonnet es mejor en conversaciones con matices y en los casos borde de calificación de leads. Conviene probar los dos contra tu caso real antes de cerrar la decisión.

Salvedad sobre el borrado: el sistema que armé no tiene soft delete ni mecanismo de corrección para los mensajes que ensuciaron la ventana de contexto. En producción querés eso, o al menos una forma de resetear el contexto sin tirar el historial.

El sistema funciona. La arquitectura es sólida para el caso de uso. Las piezas que importan para operar de verdad son la validación de firma, el tamaño de la ventana de contexto y la lógica de traspaso a humano. Las tres están.

Los archivos, incluido el concepto de arquitectura, están en este repo.

-Gonza