Crear cuenta
← Blog

·

n8n con la API oficial de WhatsApp: guía de integración

Actualizado el 25/10/2026

Para integrar n8n con la API oficial de WhatsApp tienes dos caminos: usar los nodos nativos WhatsApp Business Cloud (para enviar) y WhatsApp Trigger (para recibir), conectados directamente a una app de Meta, o usar los nodos genéricos Webhook y HTTP Request, que funcionan con la Cloud API y con cualquier proveedor que reenvíe los webhooks de Meta. Los nodos nativos se configuran más rápido; el camino genérico da más control y evita la limitación de un webhook por app.

Esta guía explica qué hace cada nodo, qué credenciales piden, los errores que más traban la integración y un flujo de ejemplo que recibe mensajes y responde automáticamente.

Los nodos de n8n para WhatsApp

Según la documentación de n8n, el nodo WhatsApp Business Cloud tiene estas operaciones:

RecursoOperaciones
MessageSend, Send and Wait for Response, Send Template
MediaUpload, Download, Delete

El WhatsApp Trigger inicia el flujo a partir de eventos de la cuenta. La página del trigger enumera: Messages, Message Template Status Update, Message Template Quality Update, Template Category Update, Phone Number Quality Update, Phone Number Name Update, Account Update, Account Review Update, Business Capability Update y Security.

Dos operaciones merecen atención:

  • Send and Wait for Response pausa el flujo hasta que la persona apruebe, rechace o complete un formulario. Sirve para aprobación humana, incluso antes de que un agente de IA ejecute una herramienta.
  • Operaciones no soportadas (marcar como leído, enviar listas interactivas, gestionar plantillas) se pueden hacer con el nodo HTTP Request usando la misma credencial de WhatsApp, con la opción Predefined Credential Type.

Credenciales: qué pide n8n

n8n usa dos tipos de credencial, según la página de credenciales de WhatsApp:

NodoTipoCampos
WhatsApp Business CloudAPI keyAccess Token y Business Account ID (el ID de la WABA)
WhatsApp TriggerOAuth2Client ID (App ID) y Client Secret (App Secret)

Del lado de Meta necesitas cuenta de desarrollador, portafolio empresarial, una app de tipo empresa con el producto WhatsApp, las URL de política de privacidad y términos completas y la app en modo Live.

Un cuidado importante: el token generado en WhatsApp > API Setup del panel de Meta es temporal. Si lo pegas en la credencial, el flujo deja de enviar cuando vence. Para producción, genera un token permanente con usuario del sistema y úsalo en el campo Access Token.

¿Quieres probar mientras lees? Crea tu cuenta en Vectalk y envía el primer mensaje por la API oficial. Crear cuenta gratis →

Camino 1: nodos nativos (WhatsApp Trigger + WhatsApp Business Cloud)

Paso a paso para un flujo de respuesta automática:

  1. Crea la credencial OAuth2 con el App ID y el App Secret de tu app.
  2. Agrega el WhatsApp Trigger y marca el evento Messages.
  3. Agrega un nodo IF para seguir solo cuando haya mensaje (el evento Messages también trae estados de entrega).
  4. Agrega el WhatsApp Business Cloud con la operación Message > Send, la credencial API key, el Sender Phone Number y el destinatario tomado del trigger.
  5. Publica el flujo.

Las tres trampas del WhatsApp Trigger

La documentación de n8n describe limitaciones que explican la mayoría de los casos de «no llega nada»:

  • Un webhook por app. Meta permite registrar solo una URL de webhook por app. Si la misma app ya envía eventos a tu CRM, n8n va a reemplazar esa URL.
  • Prueba y producción. Alternar entre la URL de prueba y la de producción sobrescribe la URL registrada. Probar un flujo publicado puede cortar el tráfico de producción. La solución sugerida es despublicar mientras pruebas y volver a publicar después.
  • Suscripción de la WABA. Publicar el flujo registra la URL, pero no suscribe la app a la cuenta de WhatsApp Business (WABA). Sin esa suscripción, los mensajes nunca llegan y no aparece ninguna ejecución con error. Una prueba exitosa en el panel de Meta no confirma la suscripción.

Para revisar y corregir la suscripción:

# Lista las apps suscritas a la WABA (usa el ID de la WABA, no el phone_number_id)
curl "https://graph.facebook.com/v26.0/WABA_ID/subscribed_apps" \
  -H "Authorization: Bearer $TOKEN"

# Suscribe la app del token a la WABA
curl -X POST "https://graph.facebook.com/v26.0/WABA_ID/subscribed_apps" \
  -H "Authorization: Bearer $TOKEN"

El token necesita el permiso whatsapp_business_management. No hagas DELETE en subscribed_apps para resolver un error de webhook: eso corta todos los eventos de la WABA. Si la WABA o el número tienen un override_callback_uri, los eventos van a esa otra URL; revísalo cuando desaparezcan mensajes.

Camino 2: Webhook + HTTP Request

El nodo Webhook recibe cualquier POST, y HTTP Request llama a cualquier API. Con ellos, n8n se convierte en un consumidor más del webhook de Meta, con el formato estándar entry[].changes[].value. Este camino conviene cuando:

  • el webhook de la app ya lo usa otro sistema, o usas un proveedor que entrega los eventos a varias URL;
  • necesitas operaciones que el nodo nativo no tiene;
  • quieres validar la firma, deduplicar eventos o responder 200 antes de procesar.

Configuraciones del nodo Webhook que hacen la diferencia:

ConfiguraciónValor recomendadoPor qué
HTTP MethodPOSTLos eventos llegan por POST
RespondImmediatelyDevuelve 200 al instante y evita reenvíos del origen mientras corre el flujo
AuthenticationHeader Auth, si el origen lo permiteImpide que cualquiera dispare el flujo
IP(s) AllowlistOpcionalRestringe quién puede llamar a la URL

El tamaño máximo de payload del Webhook es 16 MB por defecto (ajustable en instancias self-hosted con N8N_PAYLOAD_SIZE_MAX), por encima de los 3 MB que Meta indica para los payloads de webhook.

Si integras directo con Meta, la URL también debe responder a la verificación por GET: crea un segundo nodo Webhook en la misma ruta con método GET y responde con un nodo Respond to Webhook que devuelva {{ $json.query["hub.challenge"] }} después de comprobar el hub.verify_token.

Ojo también con la URL de producción: la URL de prueba solo funciona mientras el editor está «escuchando». La URL que le das a Meta o al proveedor es la de producción, activa cuando el flujo está publicado.

Flujo de ejemplo: responder mensajes recibidos

El flujo recibe el evento, separa mensajes de estados, responde con texto y, fuera del horario, avisa cuándo vuelve la atención.

Nodo 1: Webhook (POST, Respond: Immediately).

Nodo 2: Code (modo Run Once for All Items), que convierte el evento de Meta en una lista de mensajes:

const salida = [];
for (const item of $input.all()) {
  const evento = item.json.body ?? item.json;
  for (const entry of evento.entry ?? []) {
    for (const change of entry.changes ?? []) {
      const v = change.value ?? {};
      for (const msg of v.messages ?? []) {
        salida.push({
          json: {
            phone_number_id: v.metadata?.phone_number_id,
            de: msg.from,
            nombre: v.contacts?.[0]?.profile?.name ?? '',
            wamid: msg.id,
            tipo: msg.type,
            texto: msg.text?.body ?? msg.interactive?.button_reply?.title ?? '',
          },
        });
      }
    }
  }
}
return salida; // los eventos solo de estado generan una lista vacía y el flujo se detiene aquí

Nodo 3: IF con la condición de horario, por ejemplo {{ $now.setZone('America/Mexico_City').hour }} entre 8 y 18.

Nodo 4: HTTP Request (POST al endpoint de mensajes), con este cuerpo JSON:

{
  "messaging_product": "whatsapp",
  "to": "{{ $json.de }}",
  "type": "text",
  "text": { "body": "¡Hola, {{ $json.nombre }}! Recibimos tu mensaje y te respondemos enseguida." }
}

Es un mensaje libre y solo funciona porque el cliente acaba de escribir, lo que abre la ventana de atención de 24 horas. Para hablar con quien no escribió, usa Send Template o un cuerpo con "type": "template".

A partir de aquí, el flujo puede guardar el contacto en un CRM, pasar el texto a un agente de IA o abrir un ticket. Para flujos conversacionales con menús y botones, mira también Typebot con la API oficial y automatizaciones con Make y Zapier.

Cómo hacerlo con Vectalk

Con Vectalk, usa el camino 2. El WhatsApp Trigger nativo depende de una app de Meta propia; en Vectalk, los eventos llegan con el formato de Meta a la URL que registres, y puedes tener varias URL por número, así que n8n no compite por el webhook con otros sistemas.

  1. Publica el flujo y copia la URL de producción del nodo Webhook.
  2. Regístrala en Vectalk:
curl -X POST https://apis.vectalk.com.br/api/webhooks \
  -H "Authorization: Bearer $VECTALK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "TU_INSTANCE_ID",
    "url": "https://tu-n8n.ejemplo.com/webhook/whatsapp",
    "name": "n8n"
  }'
  1. En HTTP Request, usa POST https://apis.vectalk.com.br/api/messages y una credencial Header Auth con nombre Authorization y valor Bearer TU_TOKEN. Con token de instancia, el número se resuelve automáticamente; con token de organización, incluye phone_number_id en el cuerpo (el nodo Code del ejemplo ya extrae ese campo).
  2. Responde 200 en menos de 20 segundos; con Respond: Immediately, n8n lo hace por ti.

Las rutas están en la documentación de webhooks y de envío de texto (en portugués). El costo de los mensajes llega en la factura de Vectalk, sin tarjeta en Meta. Crea tu cuenta en apps.vectalk.com.br/register.

Buenas prácticas para flujos de WhatsApp en n8n

  • Deduplica por wamid. El origen puede reenviar el mismo evento. Guarda los IDs procesados (en una base de datos o en Redis) y descarta los repetidos antes de responder.
  • Trata los estados en otro flujo. Los eventos sent, delivered, read y failed llegan a la misma URL. Separarlos evita respuestas duplicadas y facilita los reportes; mira estados de mensaje por webhook.
  • No confíes en el orden. Dos mensajes seguidos del cliente pueden generar ejecuciones paralelas. Si el orden importa, usa una cola.
  • Guarda las credenciales en n8n. Nunca pongas el token fijo en un nodo Code o en el cuerpo del HTTP Request.
  • Monitorea errores. Configura un Error Workflow que avise al equipo cuando falle un envío, con el código de error de Meta (la lista está en errores de la API de WhatsApp).

Preguntas frecuentes

¿n8n tiene un nodo oficial para la API de WhatsApp?

Sí. n8n tiene el nodo WhatsApp Business Cloud (mensajes, plantillas y multimedia) y el WhatsApp Trigger (eventos de la cuenta), ambos conectados a la Cloud API de Meta.

¿Puedo usar n8n con WhatsApp por código QR?

n8n no tiene un nodo nativo para eso. Las integraciones por QR dependen de APIs no oficiales, que emulan WhatsApp Web y van contra los Términos de Servicio de WhatsApp. Mira API oficial vs. no oficial.

¿Por qué mi WhatsApp Trigger no recibe mensajes?

Las causas más comunes son que la app no esté suscrita a la WABA (subscribed_apps), que la URL de prueba haya sobrescrito la de producción o que otro sistema haya registrado su propia URL en la misma app. La sección del trigger muestra cómo revisarlo.

¿Se pueden enviar plantillas desde n8n?

Sí, con la operación Send Template del nodo WhatsApp Business Cloud o con un HTTP Request con "type": "template". El error «Bad request – please check your parameters» suele indicar parámetros fuera del orden o del tipo que espera la plantilla.

¿Necesito n8n self-hosted?

No. Los nodos funcionan en n8n Cloud y en self-hosted. En self-hosted, la URL de n8n debe ser pública y HTTPS para recibir los webhooks.

Fuentes oficiales consultadas el 25/10/2026: n8n: WhatsApp Business Cloud node, n8n: WhatsApp Trigger node, n8n: WhatsApp credentials, n8n: Webhook node, n8n: WhatsApp node common issues, Meta: webhooks de la Cloud API, Documentación de Vectalk: Webhooks.

Prueba hoy la API oficial de WhatsApp

Crea tu cuenta, genera el token y envía el primer mensaje con la guía de la documentación. Los mismos payloads y webhooks de la Cloud API de Meta.

Crear cuenta gratis
Leer la documentación