Para agentes de IA y automatización
WhatsApp para agentes de IA: API REST, nodo n8n y MCP
Un agente de IA necesita tres cosas para usar WhatsApp: herramientas para enviar, una forma de recibir y reglas de seguridad. Mira qué ofrece ZapZap hoy, qué aún no existe y cómo conectar un agente a tu instancia.
¿Cómo usa WhatsApp un agente de IA?
Un agente envía mensajes llamando a la API REST de ZapZap como una herramienta (por ejemplo, send/text y send/media) y recibe las respuestas por webhook. La autenticación es por dos encabezados, x-api-key y x-api-secret, y el archivo OpenAPI describe todos los endpoints para que el agente los lea.
Hoy esto funciona por tres caminos: la API REST con OpenAPI, el nodo de la comunidad n8n-nodes-zapzap para flujos en n8n y el agente de IA integrado en cada instancia. El servidor MCP de ZapZap aún no se ha publicado; esta página lo dice con claridad en la sección de abajo.
Formas de conectar un agente a WhatsApp
La tabla muestra lo que existe hoy (consulta del 27/10/2026) y lo que no existe.
| Camino | Situación | Para qué |
|---|---|---|
| API REST y OpenAPI | Disponible: 150+ endpoints, archivo OpenAPI en pt, en y es | Cualquier agente o framework que llame HTTP como herramienta |
| Nodo n8n-nodes-zapzap | Disponible en npm (nodo de la comunidad, versión 0.1.3), no verificado por n8n | Flujos de agente en n8n, en instalación propia |
| Webhook firmado | Disponible: eventos messages y messages_update, reintentos y firma HMAC | Entregar la respuesta del cliente al agente |
| Agente de IA por instancia | Disponible en el panel y en la API (agent-edit) | Atención sin armar el agente por fuera |
| Servidor MCP | Aún no publicado | Cuando exista, conectaría clientes MCP directo a las herramientas |
| Paquetes LangChain y CrewAI | Aún no publicados | Hoy, usa la API como herramienta HTTP |
Primera llamada, para probar la herramienta
Antes de poner la API en manos de un agente, prueba el envío con cURL. Crea la cuenta, conecta un número por código QR y copia el ID de la instancia, la clave y el secreto.
curl -X POST https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/send/text \
-H "Content-Type: application/json" \
-H "x-api-key: SUA_API_KEY" \
-H "x-api-secret: SEU_API_SECRET" \
-d '{"number":"5511999999999","text":"Olá! Aqui é o assistente da clínica."}'Dale al agente solo las herramientas que necesita, con las credenciales en variables de entorno y nunca en el prompt.
Herramientas que puede recibir el agente
Cada fila es un endpoint real de la referencia. Empieza con pocas.
| Herramienta | Endpoint | Observación |
|---|---|---|
| Enviar texto | POST /api/v1/{instanceId}/send/text | Campos number y text |
| Enviar multimedia | POST /api/v1/{instanceId}/send/media | Campos number, type, file (URL), text, docName |
| Verificar números | POST /api/v1/{instanceId}/chat/check | Campo numbers; devuelve si está en WhatsApp |
| Ver el estado de la instancia | GET /api/v1/{instanceId}/instance/status | Para que el agente sepa si puede enviar |
| Configurar el webhook | PUT /api/v1/instances/{id}/webhook | Define la URL que recibe los mensajes |
¿Y el MCP?
El Model Context Protocol (MCP) es un estándar para exponer herramientas a clientes de IA. ZapZap aún no ha publicado un servidor MCP: no hay paquete ni comando de instalación, y esta página no inventa uno.
Mientras tanto, el archivo OpenAPI de ZapZap tiene un identificador por operación, lo que permite generar un servidor MCP a partir de él. El post servidor MCP de WhatsApp para Claude y Cursor muestra el diseño. Cuando haya un servidor oficial, se anunciará aquí.
Límites y buenas prácticas para agentes
- Envía solo a quien aceptó recibir (opt-in). Un agente que escribe a quien no lo pidió aumenta el riesgo de denuncias y de bloqueo.
- Define un ritmo: el agente debe respetar intervalos entre mensajes y límites por contacto. No existe un número de mensajes por día que sea seguro con garantía.
- Deja a un humano en el circuito: reglas de traspaso a un agente, confirmación antes de acciones irreversibles y registro de cada envío.
- Guarda las credenciales fuera del prompt y dale al agente solo las herramientas necesarias. Las operaciones destructivas, como borrar una instancia, no deben estar a su alcance.
- Recuerda que ZapZap es una API no oficial: va contra los términos de WhatsApp y el número puede ser limitado o bloqueado. La función anti-bloqueo reduce el riesgo, sin eliminarlo.
Preguntas frecuentes
¿ZapZap tiene servidor MCP?
Todavía no. No hemos publicado un servidor MCP ni un paquete de instalación. Hoy el agente usa la API REST como herramienta, el nodo n8n-nodes-zapzap o el agente de IA de la propia instancia.
¿Puedo usar la API con cualquier framework de agentes?
Sí. Si el framework llama HTTP como herramienta, llama a la API de ZapZap con los encabezados x-api-key y x-api-secret. El archivo OpenAPI describe los campos de cada endpoint.
¿El nodo de n8n está verificado?
Es un nodo de la comunidad (n8n-nodes-zapzap, versión 0.1.3 el 27/10/2026), aún no verificado por n8n. Los nodos no verificados solo funcionan en n8n de instalación propia, según la documentación de n8n.
¿Cómo recibe el agente la respuesta del cliente?
Por webhook: configura la URL de tu aplicación y activa el evento messages. Valida la firma e ignora los mensajes con fromMe verdadero.
¿Usar un agente cambia el riesgo de bloqueo?
No lo elimina ni crea uno nuevo, pero un agente puede enviar demasiado rápido o a quien no lo pidió. Define ritmo, opt-in y límites, y recuerda que ninguna API no oficial garantiza que el número no será bloqueado.
¿Cuánto cuesta?
R$15 por número activo al mes, prepago, sin cobro por mensaje. El consumo de IA del agente integrado se debita del saldo. El costo del modelo de tu propio agente es con tu proveedor.
Sigue por aquí
Endpoints, campos y ejemplos
Nodo de la comunidad, HTTP Request y plantillas
Agente por instancia con traspaso a un humano
Firma, idempotencia y retry
Flujo paso a paso
Qué reduce el riesgo y qué no
Dale WhatsApp a tu agente
Crea la cuenta, conecta un número y prueba la primera llamada. R$15 por número activo al mes, sin cobro por mensaje.