Flow Builder: datos del disparador, mapeo y transformación

Visión general

Un flujo es mucho más potente cuando puede leer los datos que lo iniciaron y reutilizar la salida de cada paso. El Flow Builder ahora incluye un conjunto de funciones de datos y mapeo: el cuerpo del webhook/API se vuelve una variable, la respuesta de cualquier nodo anterior queda disponible para los siguientes, el webhook de salida puede guardar su respuesta, y dos nodos nuevos — Repetir elementos y Transformar datos — te permiten recorrer listas y manipular datos sin salir del lienzo.

Todo es opcional y retrocompatible: los flujos existentes siguen funcionando exactamente como antes.

Requisitos previos

• El módulo Flow Builder habilitado en tu cuenta.
• Administrador para editar y publicar el flujo. Los agentes pueden seguir las ejecuciones.
• Para las funciones de datos del disparador: un disparador de Webhook o API en el flujo.
• Nociones básicas de variables: en el editor, el botón de variables ({ }) y escribir {{ abren la lista de tokens disponibles. Inserta un token escribiéndolo entre llaves dobles, por ejemplo {{ trigger.body.email }}.

Paso a paso

Ejemplo: llega un pedido por webhook y quieres usar el número de pedido en un mensaje.

1. En el nodo disparador (Webhook o API), abre la sección Muestra del payload.
2. Haz clic en Obtener último evento (o Pegar JSON) para traer un ejemplo real del cuerpo.
3. En el árbol que aparece, haz clic en el valor que quieras (p. ej. order.id). Eso crea un mapeo variable ← ruta (p. ej. id ← body.order.id).
4. Opcional: Fija la muestra para guardarla en el flujo y alimentar la lista de variables del editor.
5. En cualquier nodo posterior, usa la variable mapeada ({{ vars.id }}) — o ve directo al cuerpo con {{ trigger.body.order.id }}.
6. Publica el flujo.

Configuración y opciones

Datos del disparador

• Cuerpo del webhook/API como variable: el cuerpo que inició el flujo está disponible en {{ trigger.body.campo }} — por ejemplo {{ trigger.body.order.id }} o {{ trigger.body.items[0].sku }}. Funciona con JSON y con formularios; el contenido no estructurado llega en {{ trigger.body.raw }}.
• Límite de tamaño: el cuerpo se guarda hasta 64 KB. Los payloads más grandes se truncan (se conservan los campos de nivel superior y se marca un aviso).
• Mapeo directo en el disparador: además de leer el cuerpo, puedes mapear rutas a variables con nombre ya en el disparador (variable ← ruta). Ese mapeo funciona para todas las familias de disparador, no solo webhook — las rutas son relativas al dato que inició el flujo.

Muestra del payload en el editor

Disponible en los disparadores de Webhook y de API:

El panel "Datos disponibles" en el inspector

Al seleccionar cualquier nodo, el inspector muestra el panel Datos disponibles — un catálogo de todo lo que puedes insertar, organizado en cuatro pestañas:

• Disparador — el árbol del payload del disparador (muestra fijada o la última ejecución real). Haz clic en un valor para insertar {{ trigger.… }}. ¿Aún sin muestra? Usa Obtener último evento.
• Pasos — la salida de cada nodo anterior, con los valores reales de la última ejecución. Los pasos sin salida aún muestran "aún sin salida"; los pasos renombrados o eliminados aparecen atenuados.
• Variables — las variables que produce el flujo (vars.*), con el valor de la última ejecución cuando lo hay.
• Estándar — los campos estándar de contacto, conversación, agente, bandeja, cuenta, CRM, flujo y Account Brain.

Cada campo muestra un valor de ejemplo (de la última ejecución) junto al token cuando está disponible — el mismo aparece en la lista del botón de variables ({ }). Haz clic en un campo y se inserta donde está el cursor. Los valores reflejan la última ejecución y pueden estar desactualizados; usa Actualizar para traer la más reciente.

Autoasignar campos

En las pantallas de asignación (la prueba del HTTP request, la muestra del disparador y el Webhook de salida), cuando hay una muestra de la respuesta, el botón Autoasignar campos crea una fila por cada campo de primer nivel: el nombre de la variable se normaliza (minúsculas con _) y la ruta apunta al campo. Los nombres repetidos reciben un sufijo (_2, _3), los campos ya asignados se omiten y el límite es de 20 por clic. El campo de ruta también sugiere rutas de la muestra mientras escribes.

Insertar variables en las acciones

Los nodos de acción (crear contacto, acciones de CRM, tareas, WhatsApp, etc.) ahora también ofrecen el botón de variables. Escribir {{ en un campo de texto abre la lista, y el encabezado incluye Insertar variable para las acciones compuestas solo de selectores. La variable entra en el campo enfocado, exactamente como en los mensajes.

Salidas por paso

• La respuesta de cualquier nodo anterior está disponible para los siguientes en {{ steps.nombre_del_paso.campo }}.
• El nombre del paso es la etiqueta del nodo en minúsculas con _ en lugar de espacios/símbolos (o el id del nodo cuando la etiqueta está vacía). Renombra el nodo para tener un nombre predecible.
• Campos comunes: status en cualquier nodo; el nodo de solicitud HTTP también expone body y handle (p. ej. {{ steps.consulta.body.total }}, {{ steps.consulta.status }}).

Webhook de salida: capturar la respuesta

• El nodo Webhook de salida puede, opcionalmente, guardar la respuesta en una variable y mapear campos de ella a variables con nombre (rutas con puntos, p. ej. data.id).
• Está desactivado por defecto: sin variable y sin mapeos, el comportamiento es idéntico al de antes.

Nodos nuevos: Repetir elementos y Transformar datos

Repetir elementos — recorre una lista un elemento a la vez:

• Apunta a la lista (p. ej. {{ vars.orders }}, {{ steps.consulta.body }} o una ruta con puntos).
• Cada pasada expone el elemento actual y el índice en variables (p. ej. {{ vars.item }}, {{ vars.loop_index }}).
• Conecta la salida elemento de vuelta al nodo para repetir; la salida finalizado se dispara al terminar.
• Límites: hasta 100 elementos por bucle; cada pasada gasta los pasos del cuerpo dentro del presupuesto de pasos de la sesión (por eso los bucles muy grandes pueden agotarlo — el editor avisa).

Transformar datos — manipula datos en una variable, con salidas éxito / error:

• Plantilla: genera texto a partir de una plantilla.
• JSON: produce datos estructurados (el texto debe ser un JSON válido).
• Operación de lista: aplica una operación sobre una lista — pick, filter, first, last, count, sum, unique, sort, join.
• Texto: divide texto en una lista o extrae valores con una expresión regular.

Casos de uso

• Convertir un pedido recibido por webhook en contacto, negocio, cobro y tarea encadenados.
• Recorrer elementos de una respuesta HTTP y ejecutar una acción controlada por elemento.
• Mapear IDs y estados del proveedor para esperas, condiciones y mensajes posteriores.

Mapeo a escala (payloads grandes y anidados)

El mapeo se reforzó para payloads reales — grandes, profundos y llenos de objetos anidados:

• Mapear campos automáticamente ahora baja 6 niveles y mapea todas las hojas (objetos anidados como utm{} y contact{} incluidos), derivando nombres del último segmento (utm.utm_source → utm_source) y desambiguando colisiones automáticamente (contact.id y order.id → id y order_id). Cuando hay más campos que el tope de 100 por clic, el aviso dice exactamente "Se mapearon X de Y".
• Búsqueda en todo: el selector de variables y el panel de datos ganaron búsqueda — incluso de campos más allá del tope de exhibición (el pie indica cuántos quedaron ocultos).
• Árboles gigantes bajo control: cada rama muestra 50 elementos a la vez ("Mostrar más"), con insignia de tamaño (~N KB), copiar ruta/valor al pasar el cursor y navegación por TODOS los índices de un arreglo (puedes mapear items.3.sku, no solo el primer elemento).
• Nada desaparece en silencio: cuando el servidor debe recortar una respuesta demasiado grande, las ramas eliminadas aparecen en un banner ámbar (con las rutas exactas); una ruta mapeada que no existe en el payload se convierte en un chip "ruta no encontrada" en el rastreo — la variable queda vacía, pero tú te enteras.
• Índice negativo: items.-1.sku toma el último elemento. La forma con corchetes (items[0].sku) se acepta al escribir y se convierte automáticamente.
• Condiciones más ricas: 14 operadores nuevos (termina con, está en la lista, está vacío, es número, es verdadero/falso, fechas antes/después/dentro de N días, longitud mayor/menor, lista contiene) más grupos de condiciones con TODAS/CUALQUIERA entre grupos.
• Transformar datos ganó operaciones nuevas (mínimo, máximo, promedio, recortar, invertir, aplanar, compactar, a JSON) y un modo texto (dividir en lista y extraer con regex).

Consejos, límites y buenas prácticas

• Sin ramas paralelas: el flujo avanza un paso a la vez — no hay ejecución simultánea de dos caminos ni nodos de unión. Repetir elementos procesa la lista en secuencia (lo que también permite que las esperas dentro del bucle funcionen con naturalidad).
• Los payloads grandes se truncan: el cuerpo del disparador (64 KB) y las salidas por paso tienen límites; al superarlos, el dato se trunca y se marca un aviso para que lo notes.

Solución de problemas

• Ruta no encontrada: actualiza la muestra y verifica la ruta completa, incluidos los índices del array.
• Salida ausente: confirma que el paso se ejecutó y revisa el trace por truncamiento o expulsión.
• Publicación rechazada: corrige la variable, el handle o el campo fuera de schema indicado por la validación.
• Modo de transformación no compatible: elige Plantilla, JSON, Lista o Texto. El error de la ejecución muestra el valor recibido y los identificadores válidos: template, json, array, string.

Ver también

• Flow Builder: construir flujos conversacionales visualmente
• Flow Builder: acciones nativas y el nodo de acción de contacto
• Flow Builder en la práctica: sesiones, versiones, informes y conexiones de base de datos
• Reglas de automatización: disparadores, condiciones y acciones