01 Qué es y qué obtienes
Montar un agente de WhatsApp tiene poco de IA y mucho de fontanería: webhooks, firmas, reintentos, memoria y despliegue. Este kit trae esa parte resuelta en un CLAUDE.md muy detallado. Claude Code lo lee, te hace diez preguntas sobre tu negocio y escribe el agente en tu ordenador, adaptado a tus respuestas. Tú no escribes código.
El resultado es un servidor FastAPI que recibe mensajes, llama a Claude con la información de tu negocio y el historial de ese cliente, y responde por WhatsApp. Si no sabe algo, lo dice y ofrece pasar la conversación a una persona en vez de inventar.
| Negocio | Uso típico |
|---|---|
| Restaurante o cafetería | Carta, horarios, ubicación, alérgenos. |
| Clínica o centro de estética | Información de tratamientos y recogida de datos para la cita. |
| Inmobiliaria | Primera cualificación del contacto y envío de información. |
| Tienda online | Estado de pedidos, envíos, devoluciones. |
| Software o servicios | Soporte posventa de primer nivel. |
02 Qué necesitas antes de empezar
- ✓Python 3.11 o superior (python3 --version).
- ✓Claude Code instalado y con sesión iniciada.
- ✓Una clave de la API de Anthropic (empieza por sk-ant-). Es independiente de tu suscripción de Claude: el agente en producción se factura por uso de API.
- ✓Un proveedor de WhatsApp: Meta Cloud API directamente (necesitas app de Meta tipo Business y negocio verificado) o Zernio, que se apoya en la API de Meta y simplifica el alta.
- ✓Tus documentos de negocio en texto: carta, tarifas, políticas, preguntas frecuentes.
- ✓Para producción: cuenta de GitHub y de Railway (servicio de pago) o tu propio servidor con Docker.
03 Instalación y entrevista
git clone https://github.com/Hainrixz/whatsapp-agentkit.git
cd whatsapp-agentkit
bash start.sh
claude
# ya dentro de Claude Code:
/build-agent-
1
Verificación del entorno
start.sh y la primera fase comprueban Python, crean carpetas, instalan dependencias y preparan el archivo .env.
-
2
Entrevista
Nombre y actividad del negocio, para qué quieres el agente, su nombre visible, el tono, tu horario, tus archivos de precios o carta, tu clave de Anthropic y el proveedor de WhatsApp.
-
3
Construcción
Claude escribe agent/ (servidor, cerebro, memoria, herramientas y adaptadores del proveedor), config/ (business.yaml y prompts.yaml), un simulador de chat, Dockerfile y docker-compose.
-
4
Pruebas
Hablas con el agente desde la terminal como si fueras un cliente y pides ajustes en lenguaje natural.
-
5
Puesta en marcha
Claude te guía para subir el proyecto a tu GitHub, desplegarlo en Railway, cargar las variables y registrar el webhook.
Antes de lanzar /build-agent, ayúdame a preparar la carpeta knowledge/. Te pego la información de mi negocio tal como la tengo: [carta, tarifas, horarios, políticas]. Ordénala en archivos Markdown cortos por tema, elimina lo que los clientes nunca preguntan (cada palabra va en el prompt de cada conversación y cuesta dinero) y hazme una lista de las 10 preguntas frecuentes que crees que faltan por responder.04 Probar en local
python tests/test_local.py # chat en la terminal, sin WhatsApp
uvicorn agent.main:app --reload --port 8000 # servidor local
docker compose up --build # imagen de producción
python3 scripts/audit.py # auditoría del kitCon tests/test_local.py, simula 12 conversaciones de clientes reales de mi negocio: 4 preguntas normales, 3 preguntas cuya respuesta no está en la información que te di, 2 clientes enfadados, 1 que intenta sacar un descuento, 1 que escribe en inglés y 1 que pide hablar con una persona. Para cada una dime si la respuesta es correcta, si inventó algo y qué cambiarías en config/prompts.yaml. No cambies nada hasta que lo apruebe.05 Despliegue: los fallos que más tiempo hacen perder
- ✓Configura DATABASE_URL con PostgreSQL. Sin ella el agente usa SQLite dentro del contenedor y pierde el historial en cada despliegue.
- ✓Define WHATSAPP_PROVIDER exactamente como zernio o meta, en minúsculas.
- ✓Carga el secreto del webhook (ZERNIO_WEBHOOK_SECRET o META_APP_SECRET). Sin él el agente arranca, pero no verifica la firma y cualquiera que conozca la URL podría enviarle mensajes.
- ✓No fijes la variable PORT a mano en Railway: la plataforma la inyecta y el Dockerfile la respeta.
- ✓Recuerda que cambiar el prompt en tu ordenador no cambia el agente publicado hasta que haces commit y push.
- ✓El modelo se cambia con ANTHROPIC_MODEL sin tocar código; elige uno más ligero si solo responde preguntas frecuentes.
06 Costes, privacidad y límites de WhatsApp
El kit es gratuito (licencia MIT). Pagas el alojamiento, la API de Claude y, según el caso, a Meta o al proveedor. En cada turno se reenvía a Claude el prompt completo más el historial, así que el coste crece con la longitud de tu información de negocio: recortar el prompt ahorra más que cambiar de modelo. Consulta las tarifas actuales de Anthropic, Meta y Railway antes de calcular.
WhatsApp solo permite mensajes libres en las 24 horas siguientes al último mensaje del cliente; fuera de esa ventana necesitas plantillas aprobadas por Meta. Como este agente responde a quien escribe, no suele ser un problema.
Preguntas frecuentes
Para construirlo y probarlo en local, no: respondes preguntas y Claude Code escribe el código. Para el despliegue y el webhook ayuda tener algo de soltura técnica, aunque Claude te guía paso a paso.
Sí. El proyecto usa un patrón adaptador: pídele a Claude Code que migre de un proveedor a otro y regenerará solo los archivos necesarios.
Sí. Clona el kit una vez por negocio; cada agente es independiente, con su configuración, su base de datos y su número.
Sí. Guarda el historial de cada número y lo usa en las siguientes conversaciones, siempre que en producción uses una base de datos persistente como PostgreSQL.
No de entrada. Para iniciar conversaciones fuera de la ventana de 24 horas WhatsApp exige plantillas aprobadas, y el kit está pensado para responder.
Sobre el autor
Equipo editorial de appyweb
Marketing, SEO y desarrollo con IA
Especialistas de appyweb en SEO, publicidad, desarrollo web y automatización con IA.