Resumen: Instalar la Agent Skill de Whapi con un solo comando evita los tres errores más comunes que cometen los agentes de IA con la API de WhatsApp: Chat IDs incorrectos, cabeceras de autenticación erróneas y polling en lugar de webhooks. Codifica 7 categorías de referencia y funciona con Cursor, Claude Code, Codex, GitHub Copilot y más de 40 agentes adicionales.
Instalación: npx skills add Whapi-Cloud/whapi-whatsapp-api-skill · Requiere Node.js 18+ · GitHub · Documentación
¿Qué es una Agent Skill?
Cuando usted le pide a Cursor o Claude Code que construya un bot de WhatsApp, el agente recurre a datos de entrenamiento que cubren miles de APIs — ninguna específicamente autoritativa para Whapi.Cloud tal como existe hoy. El resultado es código que parece plausible pero falla silenciosamente en producción.
Una Agent Skill es la solución. Es un archivo de conocimiento estructurado (SKILL.md) que vive en su proyecto y se carga automáticamente en el contexto del agente cuando detecta una tarea relevante. Piénselo como instrucciones permanentes: "Al desarrollar con la API de WhatsApp de Whapi.Cloud, use estos nombres de campo exactos, patrones de autenticación y reglas arquitectónicas".
El estándar fue introducido a finales de 2025 mediante vercel-labs/skills y hoy lo admiten más de 40 agentes de IA. Las skills se instalan con un único comando npx skills add. Sin archivos de configuración ni boilerplate — el agente las detecta automáticamente.
MCP es la despensa — la Agent Skill es la receta. El servidor MCP de Whapi le da a su agente 165 herramientas para llamar a la API de WhatsApp. La Agent Skill le enseña qué herramienta llamar en cada situación, qué parámetros usar y qué patrones evitar. Juntos, cierran los modos de fallo más comunes en código de WhatsApp generado por IA.
El problema: qué malinterpretan los agentes de IA sobre WhatsApp
Los agentes de codificación de IA son de propósito general. Sin un grounding específico, generan código que parece correcto pero se rompe en tiempo de ejecución. Ninguno de estos errores aparece en tiempo de compilación — solo surgen cuando la API devuelve un 400 o un 401.
Estos son los diez errores más comunes y lo que la Agent Skill de Whapi corrige:
| Lo que la IA escribe (incorrecto) | Lo que requiere Whapi.Cloud (correcto) | Impacto |
|---|---|---|
[email protected] |
[email protected] |
Formato obsoleto — cada envío devuelve 400 |
{"message": "hello"} |
{"body": "hello"} |
Nombre de campo incorrecto — el mensaje se descarta silenciosamente |
{"chat_id": "..."} |
{"to": "..."} |
Las herramientas de envío usan to, no chat_id |
X-API-Key: your_token |
Authorization: Bearer your_token |
Cabecera de auth incorrecta — 401 en cada petición |
API_KEY=your_token |
API_TOKEN=your_token |
Nombre de variable de entorno incorrecto — el servidor MCP nunca la detecta |
sendMessage() genérico |
sendMessageText, sendMessageImage, etc. |
No existe una herramienta genérica — error 400 |
Polling de getMessages en bucle |
Webhook vía updateChannelSettings |
Latencia de 5+ segundos, consume el rate limit, pierde eventos |
| Responder a todos los mensajes entrantes | Filtrar from_me: true antes de responder |
Sin este filtro, el bot se responde a sí mismo en bucle |
sendBulkMessages(recipients: [...]) |
sendMessageText una vez por destinatario, con retrasos |
Esta herramienta no existe — endpoint alucinado |
{"webhookUrl": "https://..."} |
{"webhooks": [{"url": "...", "mode": "body", ...}]} |
La configuración del webhook debe usar el array anidado webhooks[] |
Agent Skill vs. MCP: dos capas, un solo stack
Si ya usa el servidor MCP de Whapi, la Agent Skill añade la capa de conocimiento que MCP por sí solo no proporciona. Whapi.Cloud es el único proveedor de API de WhatsApp que entrega ambas.
| Agent Skill | Servidor MCP (whapi-mcp) | |
|---|---|---|
| Qué aporta | Conocimiento: cómo usar la API correctamente | Capacidad: 165 herramientas para llamar a la API |
| Método de instalación | npx skills add ... |
Añadir una entrada en mcp.json |
| ¿Requiere cuenta de Whapi? | No — se carga como contexto | Sí — necesita un API_TOKEN válido |
| ¿Realiza llamadas a la API? | No — solo archivo de referencia | Sí — ejecuta llamadas reales a la API |
| ¿Previene alucinaciones? | Sí — ese es su propósito principal | Parcialmente — los schemas de las herramientas ayudan, los patrones no |
Qué contiene la Agent Skill de Whapi
La Agent Skill de Whapi codifica 7 categorías de referencia para que su agente de IA llegue a la API ya conociendo las reglas. Cada archivo de referencia incluye ejemplos correctos e incorrectos, checklists anti-alucinación y notas específicas de Whapi.
1. Conceptos básicos (CRÍTICO)
Los errores en el formato de Chat ID son la causa individual más común de errores 400 en código de WhatsApp generado por IA. La skill codifica los tres formatos:
- Chat personal:
{phone}@s.whatsapp.net— p. ej.,[email protected] - Grupo:
{id}@g.us— obtenerlo víagetGroups; nunca construir el ID manualmente - Canal / Newsletter:
{id}@newsletter— obtenerlo víagetNewsletters
También cubre la configuración de MCP y la autenticación Authorization: Bearer {token} con el nombre correcto de variable de entorno API_TOKEN.
2. Envío de mensajes (CRÍTICO)
Un árbol de decisión completo para que el agente elija la herramienta correcta para cada tipo de contenido:
- Texto →
sendMessageText(campo:body) - Imagen JPG/PNG/WebP →
sendMessageImage(campo:media) - Vídeo MP4 →
sendMessageVideo - GIF (archivo MP4) →
sendMessageGif - Vídeo circular →
sendMessageShort - Archivo de audio MP3/WAV →
sendMessageAudio - Nota de voz OGG Opus →
sendMessageVoice - Documento/PDF →
sendMessageDocument - Sticker WebP →
sendMessageSticker - Encuesta →
sendMessagePoll - Botones/lista interactivos →
sendMessageInteractive - Ubicación →
sendMessageLocation
3. Recepción de mensajes (CRÍTICO)
Hacer polling de getMessages en bucle es el antipatrón — la recepción de mensajes de WhatsApp requiere webhooks exclusivamente. La skill enseña la estructura correcta de configuración anidada de webhooks y explica por qué el polling falla a escala: latencia de 5+ segundos, consumo continuo del rate limit, eventos perdidos entre intervalos de sondeo.
4. Grupos (ALTA)
Crear grupos, gestionar participantes, generar enlaces de invitación, asignar roles de administrador. La skill cubre todo el ciclo de vida vía createGroup, getGroups y las herramientas de gestión de participantes. Los IDs de grupo usan el formato @g.us y deben obtenerse vía la API.
5. Canales / Newsletters (ALTA)
Crear Canales de WhatsApp, publicar mensajes mediante el Chat ID @newsletter, gestionar suscriptores y administradores. Para audiencias grandes de WhatsApp, un Canal es más seguro que un bucle de difusión — sin riesgo de baneo, sin retrasos obligatorios por mensaje.
6. Comunidades (MEDIA)
Crear comunidades, vincular grupos, enviar anuncios mediante el grupo de Anuncios dedicado. Los anuncios deben enviarse específicamente a través del grupo de Anuncios — no directamente a los subgrupos.
7. Patrones de integración (ALTA)
Dos recetas listas para producción:
- Patrón de bot: Configurar webhook → recibir mensaje → filtrar
from_me: true→ responder. Funciona para bots eco, respondedores por palabra clave y asistentes impulsados por IA. - Patrón de difusión: Bucle por destinatario con retrasos obligatorios, requisitos de número calentado, reglas de personalización y comprobación de cuota vía
getLimits.
Casos de uso: dónde ayuda la skill hoy
Estos son cinco flujos concretos donde la Agent Skill de Whapi produce código correcto en el primer intento.
1. Bot de atención al cliente en WhatsApp
Usted le pide a Cursor que construya un bot de soporte. Sin la skill, Cursor escribe un bucle de polling y usa Chat IDs @c.us. Con la skill, genera un handler de webhook, filtra from_me y usa @s.whatsapp.net automáticamente. Filtre from_me: true en cada handler de respuesta del bot, o su bot de WhatsApp se mensajeará a sí mismo en un bucle infinito.
@app.route("/webhook", methods=["POST"])
def webhook():
data = request.json
if "messages" not in data:
return {"status": "ok"}
for message in data["messages"]:
if message.get("from_me"):
continue # prevent infinite loop
if message.get("type") != "text":
continue
chat_id = message["chat_id"] # e.g., "[email protected]"
text = message["text"]["body"] # correct field name: body
reply(chat_id, f"Got it: {text}")2. Notificación de lead desde un formulario web
Un nuevo lead envía un formulario. Su agente envía un mensaje de WhatsApp al equipo comercial. La skill garantiza que el agente use sendMessageText con el campo body y el Chat ID correcto @s.whatsapp.net — no un endpoint de envío genérico alucinado.
3. Sistema de notificaciones a grupos
Usted quiere publicar actualizaciones en un grupo de WhatsApp. La skill le enseña al agente que los IDs de grupo usan el formato @g.us, que debe llamar a getGroups para obtener el ID (nunca construirlo manualmente) y que el parámetro to recibe la cadena completa del Chat ID.
4. Difusión por Canal de WhatsApp
Necesita llegar a cientos de suscriptores. La skill destaca el enfoque de Canal antes que el bucle de difusión — sin riesgo de baneo, sin retrasos obligatorios por mensaje, los suscriptores se adhieren voluntariamente. Para audiencias grandes, este es el valor por defecto correcto.
5. Mensajería masiva controlada
Cuando se requiere enviar mensajes directos a una lista: máximo 10 mensajes cada 15 minutos, mínimo 60–90 segundos entre envíos, número calentado obligatorio, contenido personalizado por destinatario. Enviar mensajes de WhatsApp sin retrasos de 60 segundos ni personalización dispara la detección antispam y la suspensión de la cuenta. Llame primero a getLimits para comprobar la cuota restante.
Instalación: un comando, todos los agentes
Instale la Agent Skill de WhatsApp de Whapi con un solo comando:
npx skills add Whapi-Cloud/whapi-whatsapp-api-skillRequisito: Node.js 18 o superior.
Para apuntar a un agente específico o instalar globalmente:
# Install for Cursor only
npx skills add Whapi-Cloud/whapi-whatsapp-api-skill --agent cursor
# Install for Claude Code only
npx skills add Whapi-Cloud/whapi-whatsapp-api-skill --agent claude-code
# Install globally (available in all projects)
npx skills add Whapi-Cloud/whapi-whatsapp-api-skill --globalTras la instalación, la skill se carga automáticamente cuando su agente detecta una tarea relacionada con WhatsApp. Si no se activa por sí sola:
- Cursor: Referencie
@.agents/skills/whapi/AGENTS.mden el chat, o ejecute/whapi - Claude Code: Ejecute
/file .agents/skills/whapi/AGENTS.mdal inicio de la sesión, o ejecute/whapi - GitHub Copilot: Referencie
#.agents/skills/whapi/AGENTS.mden el chat
Configuración del servidor MCP (Cursor)
Para que el agente pueda hacer llamadas en vivo a la API de WhatsApp, añada el servidor MCP de Whapi a %USERPROFILE%\.cursor\mcp.json:
{
"mcpServers": {
"whapi-mcp": {
"command": "npx",
"args": ["-y", "whapi-mcp@latest"],
"env": { "API_TOKEN": "YOUR_TOKEN" }
}
}
}Obtenga su token en panel.whapi.cloud/dashboard. Tras guardar la configuración, reinicie Cursor y llame a checkHealth (sin argumentos) — un canal conectado devuelve "status.text": "AUTH".
Guía de instalación completa: support.whapi.cloud/help-desk/ai-tools/agent-skills
Qué no está cubierto aún — y qué está por venir
La versión actual se centra en los flujos más comunes. Algunas áreas no están todavía en los archivos de referencia de la skill:
- Mensajes interactivos (
sendMessageInteractive): Documentados, pero marcados como inestables — la entrega varía según la versión de WhatsApp. Monitoreados activamente. - Estados / Stories de WhatsApp: Disponibles en el MCP (165 herramientas), aún no documentados en las categorías de referencia de la skill.
- Commerce / Pedidos / Productos: Los flujos de catálogo y pedidos de WhatsApp están disponibles en la API, pero aún no en la biblioteca de patrones de la skill.
- Manejo avanzado de medios: Casos límite sobre codificación de archivos, límites de tamaño y streaming de audio aún no están cubiertos.
- Llamadas de WhatsApp: La detección de llamadas entrantes vía webhooks está listada; los patrones de gestión de llamadas están pendientes.
Las Agent Skills codifican años de ensayo y error con APIs en un solo archivo para que los agentes de IA salten directamente a la implementación correcta. La Agent Skill de Whapi es un documento vivo que crece con cada flujo de desarrollo que documentamos. Las contribuciones son bienvenidas.
Primeros pasos con Whapi.Cloud
La Agent Skill de Whapi es gratuita y de código abierto. Para usarla contra la API real de WhatsApp, necesita una cuenta de Whapi.Cloud — hay un sandbox gratuito disponible sin caducidad, que cubre 5 conversaciones activas y 150 mensajes al día. Sin aprobación de Meta, sin restricciones de plantillas.
- Cree una cuenta gratuita en whapi.cloud
- Empareje su número de WhatsApp mediante código QR
- Copie el token de su canal desde el dashboard
- Ejecute:
npx skills add Whapi-Cloud/whapi-whatsapp-api-skill - Añada la entrada del servidor MCP a la configuración de su agente
- Pídale a su agente: "Envía un mensaje de WhatsApp usando WHAPI"
El agente cargará la skill, verificará la conexión mediante checkHealth y le guiará a través del primer envío con los nombres de campo correctos, el formato de Chat ID y la cabecera de auth. Su primer envío funcional de WhatsApp, desde la instalación de la skill hasta la confirmación de entrega, toma menos de diez minutos.
GitHub: github.com/Whapi-Cloud/whapi-whatsapp-api-skill
Documentación: support.whapi.cloud/help-desk/ai-tools/agent-skills
Integración MCP: whapi.cloud/mcp-whatsapp-api
