# Kit: Agentes IA por WhatsApp — Conocimiento condensado

Este kit junta TODO lo aprendido construyendo el agente WhatsApp de Herrajes San José (Twilio + Meta + Claude + Whisper). Si arrancás un proyecto nuevo de "vender agentes IA por WhatsApp", **leelo entero antes de empezar** — te ahorra varios días de prueba y error.

## Quién es esto para
Quien quiera ofrecer agentes IA conversacionales por WhatsApp Business (productos, soporte, ventas, reservas, etc.) a clientes finales, usando Twilio como BSP (Business Solution Provider) y Anthropic Claude como cerebro.

## Lectura sugerida en orden

| # | Archivo | Qué cuenta |
|---|---|---|
| 1 | [`01-arquitectura.md`](01-arquitectura.md) | Cómo se conectan las piezas (webhook ↔ Claude ↔ Twilio ↔ DB ↔ Whisper). Costos. |
| 2 | [`02-onboarding-cliente.md`](02-onboarding-cliente.md) | Pasos para dar de alta un cliente nuevo: cuenta Twilio, WABA, número, webhook, env vars. |
| 3 | [`03-templates-whatsapp-realidad.md`](03-templates-whatsapp-realidad.md) | **El más importante**: todas las trampas de templates Meta que descubrimos en una sesión. |
| 4 | [`04-agente-claude-loop.md`](04-agente-claude-loop.md) | Diseño del loop agentic con tools, system prompt, historial. |
| 5 | [`05-voz-y-imagenes.md`](05-voz-y-imagenes.md) | Procesamiento de audios (Whisper) e imágenes (Claude vision). |
| 6 | [`06-troubleshooting.md`](06-troubleshooting.md) | Errores típicos (21656, 63013, etc.) y cómo diagnosticarlos. |
| 7 | [`07-modelo-negocio.md`](07-modelo-negocio.md) | Costos por conversación, márgenes posibles, pitches probables. |

## Ejemplos de código
Carpeta [`ejemplos/`](ejemplos/) — esqueletos en PHP listos para adaptar:
- [`webhook-base.php`](ejemplos/webhook-base.php) — esqueleto completo de un webhook funcionando.
- [`tablas.sql`](ejemplos/tablas.sql) — estructura de base de datos mínima.

## Lo que te va a doler menos sabiendo esto

1. **Meta cambia las reglas de templates SIN avisar**, en cualquier momento del día. Tu producto tiene que tolerar templates rechazados y fallback a texto plano.
2. **Twilio Content templates son inmutables** — no se editan, hay que crear nuevos y rotar.
3. **Quick-reply buttons NO permiten variables** `{{N}}` en títulos, ni emojis al crearse nuevos. Plan ese límite en la UX desde el día 1.
4. **El número del cliente para WhatsApp Business** no puede coexistir con la app de WhatsApp en otro celular. Si vendés a comercios, contemplá liberar la SIM antes del onboarding.

Buena suerte. — sesión 2026-06-05/07