WhatsApp AgentKit

git clone https://github.com/Hainrixz/whatsapp-agentkit.git

WhatsApp AgentKit es un kit de código abierto publicado por Hainrixz para arrancar un agente de IA conectado a WhatsApp Business sin tener que cablear toda la integración desde cero. Te da el esqueleto: la conexión con la API de WhatsApp, la estructura del agente, los puntos donde meter tu lógica de negocio y tu modelo. Tú aportas las claves, las reglas y el cerebro; el kit aporta la fontanería.

El problema que resuelve es el del tiempo perdido en lo repetitivo. Cuando montas un bot de WhatsApp con IA desde cero, dedicas las primeras semanas a cosas que ya están resueltas mil veces: recibir webhooks, gestionar la ventana de 24 horas, formatear mensajes, manejar plantillas, persistir el estado de la conversación. AgentKit te entrega todo eso ya hecho, así que el primer día puedes concentrarte en lo único que realmente diferencia a tu agente: cómo responde, qué sabe, qué acciones puede ejecutar.

A quién rinde: a desarrolladores y equipos técnicos pequeños que quieren un agente propio en WhatsApp con control total sobre el código, el modelo y los datos. No es para perfiles no técnicos (para eso hay WATI o respond.io) ni para quien quiere algo terminado y soportado por un proveedor.

Por qué importa

Importa porque el patrón “agente de IA en WhatsApp” se ha vuelto el caso de uso estrella de la mensajería de negocio: atención al cliente, calificación de leads, soporte técnico básico, recomendaciones de producto, agendado. Las plataformas SaaS lo cubren pero te encierran en sus límites y precios; un kit open-source te deja la misma capacidad técnica con libertad y a coste de tu propia infraestructura.

Importa también porque la barrera de entrada para hacer esto bien es alta. La WhatsApp Cloud API no es complicada, pero tiene esquinas (verificación de webhook, plantillas, ventanas, tokens permanentes vs temporales, manejo de medios) que cualquiera que la haya tocado a pelo conoce. Un kit que ya tiene esas esquinas resueltas te ahorra el dolor de aprenderlas a base de errores en producción.

Y al ser open-source, lo puedes auditar, modificar y desplegar donde quieras: en un VPS barato, en un contenedor en tu nube, en local para desarrollo. Los datos de las conversaciones se quedan donde decidas, no en los servidores de un tercero. Para empresas con requisitos de privacidad (sanidad, educación, finanzas), esto es decisivo.

Cómo se usa en la práctica

El punto de partida es el README del repositorio: como bien indica el frontmatter, es la fuente de verdad para los pasos exactos y los requisitos, que pueden cambiar entre versiones del kit. Cualquier guía externa (incluida esta) envejece rápido; trata el README como la verdad operativa.

A grandes rasgos, el flujo es el habitual de un proyecto open-source. Clonas el repo con el comando del frontmatter, entras en la carpeta y miras la documentación. Normalmente vas a necesitar Node.js (o el runtime que el kit indique) instalado en la máquina y un editor para tocar configuración.

Después toca conseguir las credenciales de la WhatsApp Cloud API: una app en Meta for Developers con el producto WhatsApp añadido, un número conectado, un token de acceso (temporal para probar, permanente de System User para producción) y el Phone Number ID. El kit espera estos valores en variables de entorno, así que copia el archivo de ejemplo (.env.example o equivalente) a .env y rellena.

Si el agente usa un modelo de IA (lo habitual), también necesitarás la clave del proveedor que toque: Anthropic, OpenAI, un modelo local con Ollama, lo que el kit soporte en su versión actual. Mete esa clave en el mismo archivo de configuración.

A continuación, configuras el webhook. Tu servidor tiene que exponer una URL pública con HTTPS válido para que Meta le mande los mensajes entrantes. En desarrollo, lo más cómodo es usar un túnel tipo ngrok o cloudflared para exponer tu local; en producción, despliegas en un VPS o en un servicio gestionado y apuntas el dominio. En el panel de Meta, das de alta esa URL como webhook y verificas con el token que indique el kit.

Con todo conectado, arrancas el agente y le mandas un mensaje desde tu WhatsApp al número conectado. Si todo está bien, ves la traza en los logs y recibes la respuesta del agente. A partir de ahí, abres el archivo donde vive la lógica del agente (el “prompt del sistema”, las herramientas que puede usar, las reglas de negocio) y lo adaptas a tu caso: cambias el tono, añades las preguntas que tu bot tiene que hacer, conectas con tu CRM o tu base de datos.

Para producción, despliegas en un entorno estable, configuras un token permanente, monitorizas los logs y planificas cómo manejarás los picos de mensajes y los errores. El kit te da el arranque; la operación a escala depende de ti.

Casos de uso reales

Agente de atención para una tienda online pequeña. Un comercio con cien pedidos al mes monta el kit en un VPS de cinco euros al mes, lo conecta a su catálogo y deja que el agente responda preguntas sobre productos, estado de pedido y devoluciones. Cuando la conversación se complica, el bot avisa al dueño por otro canal para que entre.

Bot de calificación de leads para una consultora. El equipo comercial recibe muchos mensajes en WhatsApp tras eventos o publicaciones en redes. El kit corre un agente que pregunta tres cosas clave (sector, tamaño, urgencia) y según las respuestas o agenda una llamada vía Calendly o cierra educadamente. El equipo solo ve los leads ya filtrados.

Asistente interno para empleados. Una empresa mediana monta el agente como asistente interno: los empleados preguntan por WhatsApp sobre políticas, vacaciones, gastos, y el agente responde consultando documentos internos. Al ser open-source y desplegado en infraestructura propia, los datos sensibles no salen de la red corporativa.

Prototipo rápido para validar una idea de producto. Un fundador que quiere probar si un servicio basado en WhatsApp tiene tracción monta el kit en una tarde, lo pone delante de veinte usuarios beta y mide. Si funciona, sigue iterando; si no, ha gastado tiempo, no presupuesto.

Errores comunes y cómo evitarlos

• Saltarse el README confiando en una guía vieja. El kit evoluciona y los pasos cambian; lee siempre la documentación actual del repo, no copias antiguas en blogs.
• Usar el token temporal en producción. El token de prueba de Meta vence en horas y deja el bot mudo. Para producción, configura un System User y genera un token permanente.
• Exponer el webhook sin HTTPS válido. Meta rechaza webhooks con certificados inválidos; en local usa un túnel tipo ngrok que ya da HTTPS, y en producción asegúrate de que el dominio tiene certificado vigente.
• No manejar la ventana de 24 horas. Fuera de esa ventana, solo plantillas aprobadas. Si tu agente intenta texto libre, falla. Detecta el tiempo desde el último mensaje del usuario y cambia la estrategia.
• Olvidar la persistencia del estado. Si el kit guarda el contexto solo en memoria, cualquier reinicio del proceso pierde las conversaciones. Configura una base de datos o el almacenamiento que el kit recomiende.
• Subir el .env al repositorio. Las claves de Meta y del proveedor de IA dan acceso a tu cuenta; tenerlas en Git público es un problema serio. Confirma que .env está en .gitignore antes del primer push.

Cuándo NO usarla

No tiene sentido si no tienes (ni quieres tener) perfil técnico para operar un servidor y depurar webhooks. En ese caso, WATI o respond.io te dan el mismo resultado funcional sin que toques código.

Tampoco encaja si necesitas garantías de soporte empresarial (SLA, integraciones empresariales certificadas, equipo de cuenta). Como cualquier proyecto open-source mantenido por una persona o un grupo pequeño, el soporte es el que la comunidad o el autor puedan dar; para entornos críticos con presupuesto, una plataforma comercial te ahorra dolores.

Y si tu caso de uso es muy estándar (bot de FAQ y poco más), montar y mantener un servidor propio puede ser desproporcionado frente a usar una plataforma no-code.

Combinarla con otras herramientas

El combo natural es AgentKit + WhatsApp Cloud API (Meta) + un proveedor de modelos (Claude, GPT, modelo local). Por encima, conviene añadir una base de datos para conversaciones (Postgres, SQLite o lo que el kit soporte), un servicio de despliegue (VPS, Render, Fly.io, Railway) y un sistema de monitorización básico (logs centralizados, alertas por errores).

Si tu negocio ya tiene CRM o backoffice, conecta el agente vía API a esas piezas para que pueda consultar pedidos, citas o fichas de cliente en tiempo real. Y si necesitas orquestación visual además del agente conversacional, herramientas como n8n o Make pueden disparar acciones desde eventos del bot.

Mini-ejercicio

Clona el repositorio con el comando del frontmatter, abre el README y sigue los pasos hasta tener el agente corriendo en local respondiendo a un mensaje de prueba desde tu WhatsApp personal. Usa un túnel tipo ngrok para exponer el webhook y el número de prueba que Meta da gratis al crear la app.

Sabrás que está bien si mandas un “hola” al número de prueba desde tu móvil y, sin tocar nada más, recibes la respuesta del agente con el modelo que hayas configurado, y ves la traza completa de la conversación en los logs de tu terminal.