WhatsApp en Dify por la API oficial, con ZapClaw

En resumen: ZapClaw envía cada mensaje de WhatsApp a un Webhook Trigger en un workflow de Dify. El workflow lo lee, consulta a tu modelo en un nodo LLM y responde con un HTTP Request. Los mensajes pasan por la Cloud API oficial de Meta, y el número sigue funcionando en la app de WhatsApp Business de tu celular. Sin servidor intermedio y sin app propia en Meta.

Conecta tu número en minutos y dale un número de WhatsApp a tu app de Dify, en Dify Cloud o en tu propia instalación.

Plan Business: US$ 29 al mes, con números ilimitados

Empieza gratis Ver los pasos

Lo que necesitas para conectar

No necesitas una empresa registrada ni un negocio verificado para conectar. La lista completa.

Por qué la API oficial para una app de Dify

Por qué un Webhook Trigger, y no la API de Dify

Dify también puede ejecutar un workflow por la API de la app (POST /v1/workflows/run), pero esa llamada exige un encabezado Authorization: Bearer con la clave de API de la app. Un webhook de ZapClaw solo envía sus propios encabezados, así que no puede llamar a esa API directamente. El Webhook Trigger acepta una solicitud HTTP simple, que es justo lo que envía ZapClaw. Si ya tienes un servidor entre ZapClaw y Dify, ese servidor puede llamar a la API de la app.

Los triggers solo funcionan en apps de tipo Workflow, no en apps Chatflow ni Agent. Un Dify self-hosted los tiene desde la versión 1.10.0, publicada en noviembre de 2025; en una instalación más antigua, actualiza primero.

Configúralo en seis pasos

  1. En Dify, crea una app de tipo Workflow. En el canvas, haz clic derecho y elige Add Node > Start > Webhook Trigger. Define el método como POST y el content type como application/json.
  2. Agrega tres parámetros del cuerpo de la solicitud y déjalos opcionales: event como String, data como Object y account como Object. Los nombres deben coincidir con las claves de ZapClaw. Un parámetro obligatorio que falte impide que el workflow arranque, y el evento de prueba del panel no trae account.
  3. Después del trigger, agrega en este orden: un nodo Code que lee el mensaje, un If-Else que solo sigue cuando text no está vacío, un nodo LLM que escribe la respuesta, un segundo nodo Code que arma el cuerpo del envío y un HTTP Request que lo envía. La configuración de cada uno está abajo.
  4. En ZapClaw, conecta tu número, crea una clave de API y pega la URL de prueba del trigger en Webhook. En Eventos a recibir, deja marcado solo Mensajes entrantes: si no, cada estado de entrega iniciaría una ejecución, y en Dify Cloud cada ejecución cuenta en la cuota de triggers. En Dify, haz clic en Run this step en el trigger y envía un mensaje de WhatsApp a tu número desde otro celular. La pestaña Last Run del trigger muestra lo que llegó.
  5. Publica el workflow y, en ZapClaw, reemplaza la URL de prueba por la URL de webhook del trigger.
  6. Envía otro mensaje de WhatsApp desde el otro celular: el workflow lo responde.

Los dos nodos Code

Los dos ejecutan Python. En el primero, conecta las variables de entrada event, data y account a las salidas del trigger y declara tres salidas String: sender, customer y text. Todo lo que no sea un texto entrante deja text vacío, así que las actualizaciones de estado y el evento de prueba terminan en el If-Else y tus propias respuestas nunca entran en bucle.

def main(event: str, data: dict, account: dict) -> dict:
    data = data or {}
    account = account or {}
    text = ""
    if event == "message.received" and data.get("type") == "text":
        text = (data.get("text") or {}).get("body") or ""
    return {
        "sender": str(account.get("display_phone_number") or account.get("phone_number_id") or ""),
        "customer": str(data.get("from") or data.get("user_id") or ""),
        "text": text,
    }

En el nodo LLM, elige tu modelo, escribe tus instrucciones en el prompt de sistema y pon el text del primer nodo Code en el prompt de usuario. En el segundo nodo Code, conecta sender y customer al primero y reply a la salida text del nodo LLM, y declara una salida Object, body. Armado en código, el cuerpo sigue siendo JSON válido, sin importar las comillas o los saltos de línea que escriba el modelo.

def main(sender: str, customer: str, reply: str) -> dict:
    return {
        "body": {"from": sender, "to": customer, "text": reply},
    }

Para probar la ida y la vuelta antes de configurar un modelo, conecta reply al text del primer nodo Code: el workflow responde con el mismo texto que recibió.

El nodo HTTP Request

El texto libre funciona dentro de las 24 horas siguientes al último mensaje del cliente. Fuera de esa ventana, Meta solo acepta una plantilla aprobada: llama a POST /api/v1/send/template.

Para probar tu clave antes de armar el workflow, haz la misma llamada desde una terminal. Un mensaje enviado responde 201.

curl -X POST https://api.zapclaw.app/api/v1/send/text \
  -H "X-API-Key: zc_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "from": "15551617409", "to": "15555550100", "text": "Hello from Dify" }'

Lo que llega al Webhook Trigger

Cada mensaje llega como un evento message.received, y el trigger le entrega al workflow sus tres claves de primer nivel: event, data con el mensaje (el texto en data.text.body, el remitente en data.from, el nombre del contacto en data.contact_name) y account con tu número. Un mensaje multimedia trae una media_url que descargas con tu clave de API.

{
  "event": "message.received",
  "sequence": 1042,
  "timestamp": "2026-05-21T14:00:00.000Z",
  "data": {
    "from": "15555550100",
    "user_id": "US.1A2B3C4D5E6F7G8H9I0J",
    "contact_name": "Maria Silva",
    "contact_username": "maria_lima",
    "message_id": "wamid.HBg...",
    "type": "text",
    "timestamp": "1747836000",
    "text": { "body": "Hello" }
  },
  "account": {
    "phone_number_id": "964283400112599",
    "display_name": "My Business",
    "display_phone_number": "+1 555 161-7409"
  }
}

Cada solicitud trae un encabezado X-ZapClaw-Signature, un HMAC-SHA256 del cuerpo sin procesar hecho con tu clave de firma: cómo verificarla (en inglés). El Webhook Trigger de Dify extrae campos y encabezados, pero no documenta una forma de leer el cuerpo sin procesar que cubre la firma, así que guarda la URL del trigger solo para ti, como una contraseña.

Conviene saber

Cuánto cuesta

Meta te cobra directamente las tarifas de mensajes de WhatsApp, sin margen de ZapClaw. Todos los planes y precios.

Para quién es

Equipos que construyen su IA en Dify y quieren llevarla a WhatsApp: respuestas desde una base de conocimiento, calificación de leads, primera línea de soporte. Las agencias conectan los números de sus clientes en el plan Agency, cada cliente aislado de los demás. No sirve para envíos masivos.

Para ir más allá

Fuentes

Revisado el 15 de octubre de 2026. Dify cambia rápido, así que, si una configuración se ve distinta, revisa la fuente. Las fuentes están en inglés.

Pon tu app de Dify en WhatsApp hoy

Empieza en el plan gratuito: un número, sin tarjeta. Pasa al plan Business cuando necesites más números o más mensajes.

Empieza gratis Ver la documentación del webhook (en inglés)