n8n

n8n es una herramienta de automatización que conecta cientos de aplicaciones (CRM, correo, Slack, hojas de cálculo). Con Orkestal te permite, por ejemplo, mandar un lead nuevo a tu CRM, avisar a tu equipo por Slack, enviar recordatorios automáticos o pasar un chat a una persona cuando se cumple una condición.

No necesitas instalar nada en n8n. Todo funciona con dos nodos que ya trae: Webhook (para recibir de Orkestal) y HTTP Request (para pedirle cosas a Orkestal).

Las dos direcciones#

Parte 1: de Orkestal a n8n#

1. Crea un Webhook en n8n#

Crea un workflow nuevo y agrega el nodo Webhook como disparador. Copia la Test URL mientras pruebas; cuando el workflow ya funcione, actívalo y usa la Production URL.

2. Agrega la acción en tu flujo#

En Flujos, en el Hacer elige la categoría Integraciones externas y la opción Enviar a webhook (n8n). Pega la URL en URL del webhook. Los otros dos campos son opcionales:

• Nombre del evento: te sirve para distinguir en n8n de qué flujo vino el aviso (por ejemplo lead.colegios).
• Secreto: si lo llenas, Orkestal firma cada envío para que puedas comprobar que viene de Orkestal. Mira Webhooks.

Cada acción tiene su propia URL, así que puedes mandar cada tipo de lead a un workflow distinto. La URL debe ser pública: por seguridad se rechazan direcciones de red interna.

3. Qué recibe n8n#

Orkestal manda el lead completo en JSON:

{
  "event": "lead.colegios",
  "sent_at": "2026-08-03T18:22:04Z",
  "business_id": "…",
  "conversation_id": "…",
  "contact_id": "…",
  "channel": "whatsapp",
  "contact": {
    "name": "María López",
    "email": "maria@ejemplo.com",
    "phone": "+5215550001111",
    "product_interest": "Primaria",
    "preference": "Turno matutino",
    "stage": "interesado",
    "tags": ["nuevo_lead", "colegios"]
  },
  "captured_data": {
    "grado_de_interes": "3ro"
  },
  "last_message": "Quiero informes de inscripciones para primaria"
}

En captured_data vienen también los campos propios que definiste en el bloque Recolectar datos de ese flujo.

Parte 2: de n8n a Orkestal#

1. Crea tu API key#

1. Entra a Integraciones → n8n y pulsa Crear API key.
2. Ponle un nombre que diga para qué es («n8n producción») y marca solo los permisos que ese workflow necesita.
3. Cópiala en ese momento: se muestra una sola vez. Si la pierdes, no hay forma de recuperarla; se revoca y se crea otra.

Detalle de permisos en Autenticación y permisos.

2. Configura la credencial en n8n#

En tu nodo HTTP Request elige:

• Authentication: Generic Credential Type
• Generic Auth Type: Header Auth
• Name: Authorization
• Value: Bearer ork_live_… (tu clave completa, con la palabra Bearer y un espacio)

Para comprobar que quedó bien, haz una petición GET /me. Si te devuelve el nombre de tu negocio, ya está conectado.

3. Rutas disponibles#

La URL base se muestra en Integraciones → n8n. El detalle de cada ruta está en la Referencia de la API.

Parte 3: las dos reglas que evitan problemas#

La ventana de 24 horas de WhatsApp#

Es una regla de Meta y la causa número uno de «mi mensaje no llegó»: solo puedes mandar texto libre si el cliente te escribió en las últimas 24 horas. Pasado ese tiempo, solo se entregan plantillas aprobadas. Como los recordatorios de pago, los carritos abandonados y los seguimientos casi siempre caen fuera de la ventana, lo normal desde n8n es usar plantilla:

POST /messages
{
  "to": "+5215550001111",
  "template": {
    "name": "recordatorio_pago",
    "variables": { "1": "María", "2": "$1,500" }
  }
}

Consulta GET /templates para ver qué plantillas tienes aprobadas y qué variables espera cada una. Si mandas texto libre fuera de la ventana, Orkestal responde con un error 409 que lo explica, en lugar de dejar que el mensaje se pierda.

Idempotency-Key: evita envíos y cobros dobles#

Cuando un nodo falla, n8n lo reintenta. Si era un envío de WhatsApp, tu cliente recibiría el mensaje dos veces y a ti te lo cobrarían dos veces. Agrega en el nodo HTTP Request la cabecera:

• Name: Idempotency-Key
• Value: un valor único por envío (por ejemplo {{ $json.id }} o {{ $execution.id }})

Si la petición se repite con la misma clave, Orkestal devuelve el resultado de la primera sin volver a enviar.

Recetas#

Lead nuevo → tu CRM y aviso al equipo. Flujo con Cuando = Nuevo lead y Hacer = Enviar a webhook (n8n). En n8n: Webhook → tu CRM (HubSpot, Pipedrive, Google Sheets) → mensaje a Slack o correo al vendedor de turno.

Recordatorio de pago o de cita. En n8n: Schedule Trigger → consulta tu sistema de cobranza → por cada pendiente, POST /messages con una plantilla aprobada y un Idempotency-Key.

Carrito abandonado o cotización sin cerrar. En n8n: tu tienda dispara el evento → nodo Wait → POST /contacts para registrar a la persona → POST /messages con plantilla de seguimiento.

Etiquetar desde fuera y dejar que Orkestal reaccione. En n8n: cuando tu sistema marca a alguien como «cliente VIP», llama POST /contacts/{id}/tags. En Orkestal, un flujo con Cuando = Se asignó una etiqueta reacciona solo, igual que si la hubiera puesto el agente.

Pasar el chat a una persona bajo cierta condición. En n8n: cuando detectas un cliente importante, una queja o un monto alto, llama POST /conversations/{id}/pause-agent y avisa a tu equipo. La IA se calla hasta que llames resume-agent o la reactives desde la bandeja.

Si algo no funciona#