Genuka WA docs

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…UsaLo que obtiene
Actúe sobre tu cuenta: enviar un mensaje, crear una plantilla, lanzar una campaña, revisar el estado de un númeroEl servidor MCP @genuka/whatsapp-mcp17 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.mdLa 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-mcp

Para 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:

.mcp.json
{
  "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?

HerramientaQué hace¿Envía o modifica algo?
list_numbersNúmeros conectados y su estadoNo
get_number_healthCalificación de calidad en tiempo real, nivel de límite de mensajes, rendimiento, alertasNo
send_text_messageTexto libre, dentro de la ventana de 24 horasEnvía un mensaje
send_template_messageUna plantilla aprobada: variables, encabezado, botones, código de un solo usoEnvía un mensaje
send_media_messageImagen, video, audio, documento o stickerEnvía un mensaje
list_templates / get_templatePlantillas, su estado y el resultado de la revisión de MetaNo
create_templateEnvía una plantilla a revisión de MetaSí
list_webhooks / create_webhookEndpoints de webhook; la creación devuelve el secreto de firma una sola vezLa creación envía los eventos de tu cuenta, incluidos los mensajes de clientes, a la URL
test_webhookEventos de ejemplo firmados enviados a tu endpointLlama a tu endpoint
list_campaigns / get_campaign / list_campaign_recipientsCampañas y entrega por destinatarioNo
create_campaignUn borrador: una plantilla, un número, una lista de destinatariosSí, no envía nada
launch_campaignEnvía la campaña a todos los destinatarios pendientesEnvía mensajes
get_subscriptionPlan, 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_webhook reenví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:

URLContenidoCuá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.txtEl primer archivo que le das a un agente
/llms-full.txtEl Markdown de todas las páginas en un solo archivoCargar toda la documentación en el contexto de una vez
Cualquier página + .mdxUna página en Markdown, p. ej. /es/docs/messages.mdxSeñalar exactamente la página que importa
/openapi.jsonDescripción OpenAPI 3.1 de /api/v1Generar un cliente tipado, o dejar que el agente verifique los nombres de los campos
/pricing.mdPlanes, precios y límites en Markdown, generados a partir del catálogo de facturaciónResponder "¿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:

AGENTS.md
## 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

En esta página