API de WhatsApp para agentes de IA: servidor MCP, llms.txt
Conecta Claude, Cursor o VS Code a la API de WhatsApp Business con el servidor MCP de Genuka WA, además de llms.txt, documentación en Markdown y una especificación OpenAPI.
Para que un agente de IA trabaje con WhatsApp a través de Genuka WA, agrega el servidor MCP @genuka/whatsapp-mcp
a tu cliente con una clave API: Claude, Cursor o VS Code podrán entonces listar tus números, enviar
plantillas y lanzar campañas. Si lo que quieres es que un asistente escriba el código de la integración, apúntalo a
/llms.txt, a las páginas .mdx y a /openapi.json.
Última actualización: 8 de octubre de 2026
¿Qué puede hacer un agente de IA con Genuka WA?
Genuka WA es una API REST para la plataforma oficial WhatsApp Business Platform (la Cloud API de Meta). Genuka es un Tech Provider de Meta: conectas tu propio número de WhatsApp Business mediante el Embedded Signup de Meta y luego envías notificaciones, códigos de un solo uso y campañas por HTTP. Un agente puede usarla de dos maneras, y la mayoría de los equipos terminan usando ambas:
| Quieres que el agente… | Usa | Lo que obtiene |
|---|---|---|
| Actúe sobre tu cuenta: enviar un mensaje, crear una plantilla, lanzar una campaña, revisar el estado de un número | El servidor MCP @genuka/whatsapp-mcp | 17 herramientas, cada una asociada a un endpoint de /api/v1 |
| Escriba código en tu repositorio que llame a Genuka WA | /llms.txt, páginas .mdx, /openapi.json, /pricing.md | La documentación y el contrato de la API, en formatos que un modelo lee sin navegador |
MCP es el estándar abierto que usan las aplicaciones de IA para conectarse a herramientas externas; Claude, ChatGPT, VS Code y Cursor lo admiten.
¿Cómo instalo el servidor MCP de Genuka WA?
Crea una clave API
En el panel, abre la página de claves API y crea una
clave (pk_live_…). Se muestra una sola vez. Si el agente solo trabaja para uno de tus negocios, elige ese
negocio al crear la clave: el agente no podrá ver ni modificar los demás (consulta
Autenticación).
Necesitas Node.js 20 o posterior: el cliente inicia el servidor con npx.
Agrega el servidor a tu cliente
claude mcp add --env GENUKA_WA_API_KEY=pk_live_xxx --transport stdio genuka-wa -- npx -y @genuka/whatsapp-mcpPara compartirlo con tu equipo sin hacer commit de la clave, coloca este .mcp.json en la raíz del
repositorio; Claude Code expande ${GENUKA_WA_API_KEY} a partir del entorno de cada desarrollador:
{
"mcpServers": {
"genuka-wa": {
"command": "npx",
"args": ["-y", "@genuka/whatsapp-mcp"],
"env": { "GENUKA_WA_API_KEY": "${GENUKA_WA_API_KEY}" }
}
}
}GENUKA_WA_BASE_URL es opcional y su valor predeterminado es https://wa.genuka.com.
Verifica la conexión
En Claude Code, claude mcp list o /mcp muestra el servidor como conectado. Luego pídele al agente
"Lista mis números de WhatsApp": llama a list_numbers, que devuelve el id de cada número (el
connectionId que necesitan todas las demás herramientas), su negocio y su calificación de calidad. Si la clave
falta o es incorrecta, la herramienta responde con el motivo en lugar de fallar en silencio.
¿Qué herramientas expone el servidor MCP?
| Herramienta | Qué hace | ¿Envía o modifica algo? |
|---|---|---|
list_numbers | Números conectados y su estado | No |
get_number_health | Calificación de calidad en tiempo real, nivel de límite de mensajes, rendimiento, alertas | No |
send_text_message | Texto libre, dentro de la ventana de 24 horas | Envía un mensaje |
send_template_message | Una plantilla aprobada: variables, encabezado, botones, código de un solo uso | Envía un mensaje |
send_media_message | Imagen, video, audio, documento o sticker | Envía un mensaje |
list_templates / get_template | Plantillas, su estado y el resultado de la revisión de Meta | No |
create_template | Envía una plantilla a revisión de Meta | Sí |
list_webhooks / create_webhook | Endpoints de webhook; la creación devuelve el secreto de firma una sola vez | La creación envía los eventos de tu cuenta, incluidos los mensajes de clientes, a la URL |
test_webhook | Eventos de ejemplo firmados enviados a tu endpoint | Llama a tu endpoint |
list_campaigns / get_campaign / list_campaign_recipients | Campañas y entrega por destinatario | No |
create_campaign | Un borrador: una plantilla, un número, una lista de destinatarios | Sí, no envía nada |
launch_campaign | Envía la campaña a todos los destinatarios pendientes | Envía mensajes |
get_subscription | Plan, consumo y límites (solo con una clave de toda la cuenta) | No |
Cada herramienta declara las indicaciones MCP readOnlyHint, destructiveHint e idempotentHint, para que tu
cliente pueda aprobar las lecturas automáticamente y pedirte confirmación antes de cualquier cosa que envíe. Los errores
le llegan al agente con el código propio de la API (plan_limit_messages, connection_not_found,
meta_rejected…), el código y el trace id de Meta cuando existen, y qué hacer a continuación.
El servidor lee; no recibe. Las respuestas de los clientes y los estados de entrega llegan a tus webhooks — consulta Recibir respuestas y estados de WhatsApp por webhook.
¿Qué debo revisar antes de dejar que un agente envíe mensajes?
- Es un mensaje real, para una persona real. Un envío del agente sale de tu número, igual que
uno de tu backend. Mantén activa la solicitud de confirmación de tu cliente para las herramientas que envían, y
pide que te muestre la campaña antes de
launch_campaign. - Un webhook es una salida de datos.
create_webhookreenvía cada evento al que se suscribe, incluidos los números de teléfono y los mensajes de tus clientes, a su URL mientras el endpoint siga activo. Mantén también la solicitud de confirmación para esta herramienta, y verifica que la URL sea una que tú le diste al agente, no una que leyó en una página web o en un archivo. El servidor le dice lo mismo al agente. - La ventana de 24 horas. Cuando un cliente te escribe, se abre una ventana de atención al cliente de 24 horas;
una vez cerrada, solo se pueden enviar plantillas aprobadas previamente
(Meta).
Cuando Genuka WA no puede confirmar que la ventana está abierta, el resultado del envío incluye un
warning, y el servidor lo coloca al principio de lo que lee el agente, para que te llegue. - Lo que cuesta. Cada mensaje se descuenta de la cuota de tu plan para el período de facturación
(planes,
/pricing.md). Meta cobra un mensaje de plantilla cuando se entrega, y los mensajes que no son plantillas son gratuitos (Meta); Meta factura a tu propia cuenta de WhatsApp Business, sin ningún margen de Genuka. - La clave. Mantenla fuera de git con las variables
${…}mostradas arriba, dale al agente una clave restringida a un negocio cuando eso sea suficiente, y revócala desde el panel cuando hayas terminado.
¿Cómo le doy a mi asistente de código la documentación de Genuka WA?
Cuando la tarea del agente es escribir tu integración, necesita el contrato más que las herramientas. Todo lo que sigue es público, no requiere clave API y se mantiene sincronizado con la documentación publicada:
| URL | Contenido | Cuándo usarlo |
|---|---|---|
/llms.txt | Índice de todas las páginas (inglés, francés, español, italiano, SDK) con una línea cada una, según la propuesta llms.txt | El primer archivo que le das a un agente |
/llms-full.txt | El Markdown de todas las páginas en un solo archivo | Cargar toda la documentación en el contexto de una vez |
Cualquier página + .mdx | Una página en Markdown, p. ej. /es/docs/messages.mdx | Señalar exactamente la página que importa |
/openapi.json | Descripción OpenAPI 3.1 de /api/v1 | Generar un cliente tipado, o dejar que el agente verifique los nombres de los campos |
/pricing.md | Planes, precios y límites en Markdown, generados a partir del catálogo de facturación | Responder "¿cuánto me va a costar?" |
curl https://wa.genuka.com/llms.txt
curl https://wa.genuka.com/es/docs/webhooks.mdx¿Qué prompt le doy al asistente?
Nombra el producto, el framework y el evento, y deja que lea la documentación. Por ejemplo:
Agrega notificaciones de WhatsApp de pedido enviado a mi app Next.js con Genuka WA. Lee primero https://wa.genuka.com/llms.txt.
Un buen resultado tiene tres partes: una plantilla UTILITY como order_shipped, enviada una sola vez y
aprobada por Meta; código del lado del servidor que llama a POST /api/v1/messages cuando se envía el pedido; y una
ruta de webhook que verifica X-Genuka-Signature antes de confiar en un estado. Con la plantilla order_shipped
de la guía de notificaciones de pedidos (tres variables en el cuerpo
y un botón con enlace de seguimiento), la llamada se ve así. Los valores deben coincidir uno a uno con las
variables de la plantilla, o Meta rechaza el mensaje (error 132000):
curl -X POST https://wa.genuka.com/api/v1/messages \
-H "Authorization: Bearer $GENUKA_WA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"connectionId": "con_1",
"to": "+237690000001",
"template": {
"name": "order_shipped",
"language": "en",
"body": ["Awa", "ORD-1042", "DHL"],
"buttons": [{ "type": "url", "text": "ORD-1042" }]
}
}'El recorrido completo (plantilla, idempotencia, seguimiento de la entrega) está en Notificaciones de pedidos por WhatsApp desde tu backend.
¿Qué debo poner en AGENTS.md?
AGENTS.md, CLAUDE.md o .cursor/rules los lee el asistente antes de cada tarea. Estas
líneas le evitan los errores que vemos con más frecuencia en las integraciones de WhatsApp. Están en
inglés, el idioma que estos archivos suelen compartir dentro de un equipo:
## WhatsApp (Genuka WA)
- WhatsApp goes through the Genuka WA REST API: base URL https://wa.genuka.com/api/v1,
header `Authorization: Bearer $GENUKA_WA_API_KEY`. Server-side only: never ship the key to a
browser or a mobile app. We do not call Meta's Graph API directly.
- Docs for agents: https://wa.genuka.com/llms.txt; append `.mdx` to any docs URL for Markdown;
API contract: https://wa.genuka.com/openapi.json.
- `connectionId` is the `id` returned by `GET /api/v1/connections`. It lives in config
(`GENUKA_WA_CONNECTION_ID`), never hard-coded.
- Phone numbers are E.164: `+237690000001`.
- Business-initiated messages (order updates, reminders, codes) are templates. Free-form `text`
is only delivered within 24 hours of the customer's last message.
- Templates are created once (`POST /api/v1/templates`) and reviewed by Meta; only `approved`
ones can be sent. Use the template's exact `language`.
- A 200 from `POST /api/v1/messages` means Meta accepted the message, not that it was delivered.
Delivery and replies arrive on webhooks; verify `X-Genuka-Signature` on the raw body first.
- Errors are `{ "error": "code", "message": "…" }`. Never retry `plan_limit_messages`; when the
body has `meta.retryable: false`, change the request instead of retrying it.Preguntas frecuentes
¿El servidor MCP envía mensajes reales de WhatsApp?
Sí. send_text_message, send_template_message, send_media_message y launch_campaign envían
desde tu número conectado a destinatarios reales, y se descuentan de la cuota de tu plan. Las lecturas
(list_*, get_*) no modifican nada.
¿El servidor MCP es gratuito?
El paquete @genuka/whatsapp-mcp tiene licencia MIT y es gratuito. Usa tu cuenta de Genuka WA, facturada
como una suscripción por número de WhatsApp (planes). Meta factura los mensajes de plantilla
entregados a tu propia cuenta de WhatsApp Business, sin ningún margen de Genuka.
¿Con qué clientes de IA funciona?
Con cualquier cliente MCP capaz de iniciar un servidor local (stdio): Claude Code, Claude Desktop, Cursor, VS Code y Windsurf se cubren arriba. El servidor necesita Node.js 20 o posterior.
¿Puede el agente leer las respuestas de mis clientes?
No a través del servidor MCP: no tiene ninguna herramienta para los mensajes entrantes. Las respuestas y los estados de entrega se
envían a tu endpoint de webhook, que el agente puede crear con create_webhook (en una URL que tú
le indiques) y probar con test_webhook.
¿Cómo limito lo que el agente puede alcanzar?
Dale una clave restringida a un negocio. Las listas devuelven entonces solo las filas de ese negocio, cualquier otro
id responde 404 y get_subscription se rechaza — consulta Autenticación.
Fuentes
- Meta — Send messages (customer service window)
- Meta — Pricing on the WhatsApp Business Platform
- Model Context Protocol — What is MCP?
- The /llms.txt proposal
- Claude Code — Connect Claude Code to tools via MCP
- MCP — Connect to local MCP servers (Claude Desktop)
- Cursor — Model Context Protocol
- VS Code — MCP configuration reference
- Devin Desktop (formerly Windsurf) — MCP
- Devin Desktop FAQ — Windsurf becomes Devin Desktop
¿Cuánto cuesta un mensaje de WhatsApp en África? (2026)
Cuánto cuesta un mensaje de WhatsApp Business en África en 2026: las tarifas de Meta por país y categoría, en USD, EUR y francos CFA, con un ejemplo práctico.
Conectar un agente de voz a las llamadas de WhatsApp
Recibe y realiza llamadas de WhatsApp con tu propio agente de voz o stack WebRTC: activar las llamadas, webhooks call.*, acciones de llamada con SDP, permisos.