whatsapp-agentkit

Ver el sitio · Inicio rápido · Cómo funciona · FAQ

About

WhatsApp AgentKit convierte una conversación de 20 minutos en un agente de WhatsApp
que atiende a tus clientes.

No es una plantilla que copias y adaptas. Es un sistema de instrucciones que Claude Code
lee para entrevistarte sobre tu negocio y después escribir, probar y desplegar el agente
completo por ti: el servidor, la conexión con WhatsApp, la memoria de cada cliente y el
prompt que le da personalidad.

Tú no escribes código. Respondes preguntas.

Lo hicimos porque el 90% del trabajo de montar un agente de WhatsApp no es la IA — es la
plomería: webhooks, firmas, tokens, reintentos, deploy. Esa parte ya está resuelta y
auditada acá adentro. Lo que queda es lo único que solo tú sabes: cómo funciona tu negocio.

Es open source, licencia MIT, y está escrito en español porque se hizo para builders
de LATAM.

Inicio rápido

git clone https://github.com/Hainrixz/whatsapp-agentkit.git
cd whatsapp-agentkit
bash start.sh

Después abre Claude Code y escribe el comando:

claude
# dentro de Claude Code:
/build-agent

Y ya. Claude Code te guía desde ahí.

Cómo funciona

start.sh solo verifica tu entorno. El sistema real arranca con /build-agent, que hace
que Claude Code lea CLAUDE.md y ejecute cinco fases.

Fase 1 — Verifica tu entorno

Chequea Python 3.11+, crea las carpetas, instala las dependencias y prepara el .env.

Fase 2 — Te entrevista

Diez preguntas, una por una: cómo se llama tu negocio, a qué se dedica, para qué quieres
el agente, cómo se va a llamar, qué tono debe tener, tu horario, tus archivos de precios
o menú, tu API key de Anthropic, y con qué servicio vas a conectar WhatsApp.

Fase 3 — Construye el agente

Con tus respuestas escribe todo esto:

tu-proyecto/
├── agent/
│   ├── main.py              Servidor que recibe los mensajes de WhatsApp
│   ├── brain.py             Conexión con Claude — el cerebro
│   ├── memory.py            Historial de cada cliente + deduplicación de eventos
│   ├── tools.py             Herramientas específicas de tu negocio
│   └── providers/           Conexión con tu servicio de WhatsApp
│       ├── base.py          Interfaz común
│       ├── __init__.py      Elige el proveedor automáticamente
│       └── zernio.py        Adaptador (o meta.py)
│
├── config/
│   ├── business.yaml        Los datos de tu negocio
│   └── prompts.yaml         El prompt que define la personalidad del agente
│
├── knowledge/               Tus archivos: menú, precios, políticas, FAQ
├── tests/test_local.py      Simulador de chat en tu terminal
├── Dockerfile               Para producción
├── docker-compose.yml
└── .env                     Tus API keys — nunca se sube a GitHub

Fase 4 — Lo pruebas

Un chat en tu terminal donde tú escribes como si fueras un cliente:

Tu: Hola, qué horarios tienen?
Agente: Hola! Atendemos de lunes a viernes de 9am a 6pm.
        Te ayudo con algo más?

Tu: Cuánto cuesta el americano?
Agente: El americano está en $45 pesos.
        Quieres que te aparte uno?

Si algo no te gusta, se lo dices a Claude Code y lo ajusta ahí mismo.

Fase 5 — Lo pones en línea

Te guía para subirlo a GitHub, conectarlo con Railway, cargar las variables de entorno y
configurar el webhook. Desde ese momento, cualquiera que te escriba por WhatsApp habla
con tu agente.

Conectar con WhatsApp

Eliges uno de los dos durante el setup.

Zernio (zernio.com) es el camino corto: creas la cuenta, conectas
tu WhatsApp Business desde el dashboard, copias la API key y listo. Si todavía no tienes
número de WhatsApp Business, su sandbox te deja ver el agente funcionando hoy mismo —
respondes un mensaje desde tu celular y quedas activado.

Meta Cloud API (developers.facebook.com) te da
control total sobre la integración. Es más trabajo de configuración inicial.

Cambiar de uno a otro después es una frase: abre Claude Code y dile "quiero migrar de
Zernio a Meta Cloud API".

Qué pasa cuando un cliente escribe

Un cliente escribe "Hola" por WhatsApp
         │
         ▼
Tu proveedor (Zernio o Meta) recibe el mensaje
         │
         ▼  webhook POST /webhook
main.py verifica la firma del webhook
         │
         ▼
providers/ normaliza el mensaje a un formato común
         │
         ▼
memory.py: ¿ya procesamos este evento? → si sí, se descarta
         │
         ▼
main.py responde 200 AHORA y encola el trabajo
         │
         ▼  ──────── fuera del ciclo del webhook ────────
memory.py busca el historial de ESE cliente
         │
         ▼
brain.py llama a Claude con el system prompt + historial + mensaje
         │
         ▼
providers/ envía la respuesta por WhatsApp
         │
         ▼
El cliente recibe la respuesta en segundos

Tres decisiones de diseño que importan:

Responde primero, trabaja después. Los proveedores esperan una confirmación en unos
5 segundos y, si no la reciben, reintentan el mismo mensaje hasta 7 veces. Llamar a Claude
tarda más que eso. Por eso el webhook confirma de inmediato y procesa en segundo plano —
si no, el cliente recibiría la misma respuesta siete veces.

Deduplica por id de evento. La entrega es at-least-once: el mismo mensaje puede
llegar dos veces. La base de datos garantiza que solo se responda una.

Verifica la firma. Cada webhook viene firmado con HMAC-SHA256. Sin esa verificación,
cualquiera que conozca tu URL podría inyectarle mensajes a tu agente.

Además: cada cliente tiene su propio historial. Si alguien te escribe hoy y vuelve
mañana, el agente recuerda la conversación anterior. Y nunca inventa información — si no
sabe algo, lo dice y ofrece pasar el contacto a una persona.

Requisitos

1. Python 3.11 o superior

• Mac: brew install python o python.org
• Windows: python.org (marca "Add to PATH")
• Linux: sudo apt install python3.11
• Verifica: python3 --version

2. Claude Code

# necesitas Node.js primero: https://nodejs.org
npm install -g @anthropic-ai/claude-code
claude   # solo la primera vez, para autenticarte

3. API key de Anthropic
platform.anthropic.com → Settings →
API Keys → Create Key. Empieza con sk-ant-....

4. Una cuenta de WhatsApp API
Zernio (recomendado) o
Meta Cloud API.

Cuánto cuesta

AgentKit es gratis y open source. Lo que pagas es el uso:

Elegir el modelo de Claude

Se cambia con la variable ANTHROPIC_MODEL, sin tocar código.

Para dar una idea: una conversación típica de WhatsApp son unos pocos miles de tokens.
Con Sonnet 5, atender cientos de conversaciones al mes cuesta unos pocos dólares.

Casos de uso

Comandos útiles

# Probar el agente sin WhatsApp (chat en terminal)
python tests/test_local.py

# Arrancar el servidor localmente
uvicorn agent.main:app --reload --port 8000

# Build Docker para producción
docker compose up --build

# Ver logs del agente
docker compose logs -f agent

# Auditar este repo (los 6 chequeos del sistema)
python3 scripts/audit.py

Personalizarlo después

No necesitas tocar código. Abre Claude Code y pídele cambios en lenguaje natural:

claude "El agente está muy formal. Hazlo más amigable y casual."
claude "Agregamos servicio de delivery. Actualiza el agente."
claude "Quiero que pueda consultar disponibilidad de citas."
claude "Quiero migrar de Zernio a Meta Cloud API."

Stack técnico

El sistema usa un patrón adaptador para los proveedores: cada uno implementa la misma
interfaz, así que main.py no sabe ni le importa cuál estás usando. Solo llama
proveedor.verificar_firma(), proveedor.parsear_webhook() y proveedor.enviar_mensaje().

Preguntas frecuentes

¿Necesito saber programar?
No. Claude Code escribe todo el código. Tú respondes preguntas sobre tu negocio.

¿Puedo usarlo con mi negocio real?
Sí. Después de probarlo localmente lo subes a Railway y queda atendiendo de verdad.

¿Y si el agente no sabe algo?
Responde algo como "No tengo esa información, déjame conectarte con alguien del equipo."
Nunca inventa datos.

¿Puedo tener varios agentes?
Sí. Clona el repo una vez por negocio. Cada agente es independiente.

¿Puedo cambiar de proveedor de WhatsApp después?
Sí. Abre Claude Code y dile qué quieres cambiar. Regenera los archivos necesarios.

¿El agente puede escribirle primero a un cliente?
No de entrada, y no es una limitación de AgentKit: WhatsApp solo permite texto libre
dentro de las 24 horas posteriores al último mensaje del cliente. Fuera de esa ventana
hace falta una plantilla aprobada por Meta. Como el agente siempre responde a alguien que
acaba de escribir, en la práctica nunca es un problema.

¿Qué pasa con mis datos?
Todo corre en tu infraestructura: tu servidor, tu base de datos, tus API keys. AgentKit
no tiene backend ni telemetría.

Contribuir

Los issues y pull requests son bienvenidos. Antes de abrir un PR, corre la auditoría:

python3 scripts/audit.py

Verifica que el código de las plantillas compile, que el YAML parsee, que las variables de
entorno estén documentadas y que los links del README respondan.

Créditos

Creado por Todo de IA — @soyenriquerocha

Construido con Claude Code para builders de LATAM.

Licencia

MIT — Usa este proyecto como quieras, para lo que quieras.