API de WhatsApp para agentes de IA: conectando Claude, n8n y LangChain

Los tres usan la misma API REST: https://api.zapzapapi.com/api/v1/{instanceId}/..., autenticada con dos encabezados, x-api-key y x-api-secret (autenticación). Si tu framework lee OpenAPI, la especificación es pública: OpenAPI de ZapZap. La página de agentes de IA reúne las tres opciones en un solo lugar.

MCP (Model Context Protocol) permite que un cliente de IA descubra herramientas de un servidor y las llame durante la conversación. zapzap-mcp expone 25 herramientas curadas (enviar texto y multimedia, encuestas, botones, comprobar números, buscar mensajes, grupos, webhooks) en lugar de más de 150 endpoints crudos, para que el modelo se equivoque menos al elegir.

El código es abierto, está en github.com/zapzapapi/zapzap-mcp y todavía no está publicado en npm. Por eso la instalación es desde el repositorio: clona, instala y compila (Node 18 o más nuevo). Luego apunta el cliente al archivo compilado.

Dos comportamientos importantes. Las herramientas de envío están marcadas como no idempotentes y destructivas, así que el cliente MCP pide confirmación en cada envío. Y ZAPZAP_READ_ONLY=true quita todas las herramientas de escritura, que es el valor correcto durante la primera semana (ya viene activado en los ejemplos).

Pide algo como: comprueba si mi instancia está conectada y dime cuáles de estos tres números tienen WhatsApp. Aprueba cada llamada a mano hasta que confíes. Si prefieres escribir tu propio servidor, el paso a paso del servidor MCP tiene el código en TypeScript.

git clone https://github.com/zapzapapi/zapzap-mcp
cd zapzap-mcp
npm install
npm run build
# Claude Code:
claude mcp add zapzap -e ZAPZAP_API_KEY=your-api-key -e ZAPZAP_API_SECRET=your-api-secret -e ZAPZAP_READ_ONLY=true -- node "$(pwd)/dist/src/index.js"

{
  "mcpServers": {
    "zapzap": {
      "command": "node",
      "args": ["/path/to/zapzap-mcp/dist/src/index.js"],
      "env": {
        "ZAPZAP_API_KEY": "your-api-key",
        "ZAPZAP_API_SECRET": "your-api-secret",
        "ZAPZAP_READ_ONLY": "true"
      }
    }
  }
}

El flujo tiene cinco nodos. 1) Webhook recibe el evento messages de la instancia (registra la URL de producción en el endpoint de webhook). 2) Code extrae número, texto e id del mensaje y descarta los eventos con fromMe verdadero; sin eso el agente responde a sus propias respuestas en bucle. 3) AI Agent con memoria de ventana, usando el número del contacto como clave de sesión, para que cada cliente tenga su propia conversación; pon la regla de traspaso a una persona en el prompt de sistema, por ejemplo responder con una frase fija cuando el cliente pida a alguien. 4) IF detecta esa frase fija y marca el contacto como con humano. 5) HTTP Request llama a POST /api/v1/{instanceId}/send/text con number y text.

También existe un nodo de la comunidad, n8n-nodes-zapzap (versión 0.1.3 en npm). Los nodos de comunidad no verificados solo corren en n8n self-hosted; en n8n Cloud usa HTTP Request con los mismos encabezados. El paso a paso completo está en agente de IA en WhatsApp con n8n, y hay flujos listos en las plantillas de n8n.

Una herramienta es una función con nombre, descripción y argumentos tipados. El modelo decide cuándo llamarla; la función decide qué está permitido. Los seguros van en la función, nunca en el prompt. El ejemplo de abajo tiene dos herramientas: comprobar números y enviar texto solo a una lista permitida, con el envío apagado hasta que definas ZAPZAP_ENABLE_SEND=true.

Conecta las herramientas a un agente con LangChain 1.x (create_agent) o con el decorador tool de CrewAI, y revisa la documentación de tu versión, porque ambos proyectos cambian rápido. La aprobación humana antes del envío real viene de las funciones de interrupción o human-input de tu framework. La versión completa está en la guía de LangChain y CrewAI.

import os
import re
import requests
from langchain_core.tools import tool

BASE = "https://api.zapzapapi.com/api/v1"
INSTANCE = os.environ["ZAPZAP_INSTANCE_ID"]
HEADERS = {
    "x-api-key": os.environ["ZAPZAP_API_KEY"],
    "x-api-secret": os.environ["ZAPZAP_API_SECRET"],
}
ALLOWED = {n.strip() for n in os.environ.get("ZAPZAP_ALLOWED", "").split(",") if n.strip()}
SEND_ENABLED = os.environ.get("ZAPZAP_ENABLE_SEND") == "true"


def _post(path: str, body: dict) -> dict:
    r = requests.post(f"{BASE}/{INSTANCE}{path}", json=body, headers=HEADERS, timeout=20)
    r.raise_for_status()
    return r.json()


@tool
def check_whatsapp_numbers(numbers: list[str]) -> str:
    """Check which phone numbers are registered on WhatsApp.
    Numbers: country code plus digits only, for example 5511999999999."""
    clean = [n for n in numbers if re.fullmatch(r"\d{10,15}", n)]
    if not clean:
        return "No valid numbers. Use country code and digits only."
    return str(_post("/chat/check", {"numbers": clean}))


@tool
def send_whatsapp_text(number: str, text: str) -> str:
    """Send a WhatsApp text to ONE allowed recipient. Never invent numbers."""
    if not re.fullmatch(r"\d{10,15}", number):
        return "Invalid number format."
    if number not in ALLOWED:
        return "Blocked: this number is not on the allowed list."
    if len(text) > 1000:
        return "Blocked: text too long."
    if not SEND_ENABLED:
        return f"Safe mode, not sent. Would send to {number}: {text[:80]}"
    return str(_post("/send/text", {"number": number, "text": text}))

from langchain.agents import create_agent

agent = create_agent(
    model="provider:model-name",   # fill in the provider you have a key for
    tools=[check_whatsapp_numbers, send_whatsapp_text],
    system_prompt="You help the support team. Only message people on the allowed list.",
)
result = agent.invoke({"messages": [{"role": "user", "content": "Is 5511999999999 on WhatsApp?"}]})

Una API no oficial va contra los términos de WhatsApp y un número puede ser limitado o bloqueado. Un agente no reduce ese riesgo; puede aumentarlo si empieza conversaciones en frío en volumen. Funciones antibloqueo, como el escribiendo automático y el ritmo de envío, reducen el riesgo, no lo eliminan, y nadie honesto promete lo contrario.

Usa agentes para responder a quien escribió primero, apoyar al equipo y tareas internas, y escribe solo a quien aceptó recibir mensajes. Consulta la guía antibloqueo y la política de uso aceptable. Si necesitas un canal oficial, usa la Cloud API de Meta: el comparativo oficial vs no oficial muestra cuándo gana cada una.

R$15 por número activo al mes, prepago, sin cobro por mensaje (precios). Las cuentas nuevas reciben un crédito de bienvenida al verificar el teléfono, según la campaña vigente. El inicio rápido te lleva de la cuenta al primer mensaje.