Flows y ejecuciones

Endpoints de Flow Studio: gestionar flujos, carpetas, plantillas, la Bóveda, variables globales, dispararlos y revisar sus ejecuciones. Todos cuelgan de /workspaces/:workspaceId/flows y requieren autenticación.

Flujos

Método	Ruta	Descripción
GET	/flows	Listar flujos
GET	/flows/:flowId	Obtener flujo
POST	/flows	Crear flujo
PATCH	/flows/:flowId	Actualizar flujo
DELETE	/flows/:flowId	Eliminar flujo
GET	/flows/:flowId/validate	Validar flujo
POST	/flows/:flowId/trigger	Disparar manualmente
POST	/flows/:flowId/regenerate-token	Regenerar token de webhook

Precaución

Validar es GET, no POST — no muta el flujo, solo corre las mismas reglas que bloquean guardar/activar en el editor.

Carpetas

Método	Ruta	Descripción
GET	/flows/folders	Listar carpetas
POST	/flows/folders	Crear carpeta
PATCH	/flows/folders/:folderId	Actualizar carpeta (renombrar o mover)
DELETE	/flows/folders/:folderId	Eliminar carpeta

Plantillas de flow

Método	Ruta	Descripción
GET	/flows/templates	Listar plantillas
GET	/flows/templates/:templateId	Obtener plantilla
POST	/flows/templates	Crear plantilla
PATCH	/flows/templates/:templateId	Actualizar plantilla
DELETE	/flows/templates/:templateId	Eliminar plantilla
POST	/flows/templates/:templateId/use	Usar plantilla (incrementa su contador de uso)

Bóveda (secrets)

Valores cifrados (API keys, tokens de terceros) que se referencian en un flujo como {{boveda.nombre}} sin exponerlos. Solo el OWNER del workspace, o un miembro con la capability boveda:manage, puede crear/editar/borrar — el GET queda abierto a todo el workspace para que el selector de variables pueda listar los nombres.

Método	Ruta	Descripción
GET	/flows/secrets	Listar secrets (valor enmascarado)
POST	/flows/secrets	Crear secret
PATCH	/flows/secrets/:secretId	Actualizar secret
DELETE	/flows/secrets/:secretId	Eliminar secret

Variables globales

El par “público” de la Bóveda: valor en texto plano, visible y editable por cualquier miembro del workspace (no requiere ninguna capability especial). Se usan en un flujo como {{globalVars.nombre}}.

Método	Ruta	Descripción
GET	/flows/global-vars	Listar variables globales
POST	/flows/global-vars	Crear variable global
PATCH	/flows/global-vars/:varId	Actualizar variable global
DELETE	/flows/global-vars/:varId	Eliminar variable global

Ejecuciones

Método	Ruta	Descripción
GET	/flows/executions	Listar todas las ejecuciones del workspace
GET	/flows/:flowId/executions	Listar ejecuciones de un flujo concreto
GET	/flows/executions/:executionId	Detalle de una ejecución
POST	/flows/executions/:executionId/cancel	Cancelar una ejecución en curso

---

Crear flujo

POST /workspaces/:workspaceId/flows Copiar

Cuerpo de la petición

Campo	Tipo	Requerido	Descripción
name	string	Sí	Nombre del flujo.
description	string	No	Descripción.
nodes	array	No	Nodos del flujo (formato de React Flow). Si vienen, se validan igual que en el editor.
edges	array	No	Conexiones entre nodos.
variables	array	No	Variables propias del flujo (name, value, type, scope).
settings	object	No	triggerType, triggerConfig, timeout, maxConcurrent, environment. Si se omite triggerType, se infiere del nodo trigger.
tags	array de string	No	Etiquetas para organizar la biblioteca.
folderId	string | null	No	Carpeta donde se ubica el flujo.

Consejo

Si triggerType resulta ser webhook (por settings.triggerType o por el nodo trigger presente), la API genera automáticamente el webhookToken — no lo envíes tú.

cURL

curl -X POST "https://api.waiify.com/workspaces/WORKSPACE_ID/flows" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bienvenida a nuevos leads",
    "description": "Envía WhatsApp de bienvenida al crear un contacto",
    "tags": ["onboarding"]
  }'

Node

const res = await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/flows',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer TU_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Bienvenida a nuevos leads',
      description: 'Envía WhatsApp de bienvenida al crear un contacto',
      tags: ['onboarding'],
    }),
  }
);

const { data: flow } = await res.json();

Python

import requests

res = requests.post(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/flows",
    headers={"Authorization": "Bearer TU_API_KEY"},
    json={
        "name": "Bienvenida a nuevos leads",
        "description": "Envía WhatsApp de bienvenida al crear un contacto",
        "tags": ["onboarding"],
    },
)

flow = res.json()["data"]

Respuesta 201

{
  "success": true,
  "message": "Flow creado",
  "data": {
    "id": "flow_ab12cd34ef",
    "name": "Bienvenida a nuevos leads",
    "description": "Envía WhatsApp de bienvenida al crear un contacto",
    "folderId": null,
    "nodes": [],
    "edges": [],
    "variables": [],
    "settings": { "triggerType": "manual" },
    "triggerType": "manual",
    "webhookToken": null,
    "isActive": false,
    "version": 1,
    "tags": ["onboarding"],
    "createdAt": "2026-06-18T09:00:00.000Z",
    "updatedAt": "2026-06-18T09:00:00.000Z"
  }
}

Actualizar flujo

PATCH /workspaces/:workspaceId/flows/:flowId Copiar

Cuerpo de la petición

Todos los campos son opcionales; solo se actualiza lo que envíes. Además de los campos de creación, acepta:

Campo	Tipo	Descripción
isActive	boolean	Activa o pausa el flujo.
expectedVersion	number	Versión que tenías cargada al editar. Si no coincide con la actual, la API responde 409 en vez de sobrescribir los cambios de otro usuario (optimistic locking).

Precaución

Si vienen nodes/edges, se validan como en el editor: un flujo con errores de estructura responde 400 y no se guarda.

cURL

curl -X PATCH "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/FLOW_ID" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "isActive": true, "expectedVersion": 3 }'

Node

await fetch('https://api.waiify.com/workspaces/WORKSPACE_ID/flows/FLOW_ID', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer TU_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ isActive: true, expectedVersion: 3 }),
});

Python

import requests

requests.patch(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/FLOW_ID",
    headers={"Authorization": "Bearer TU_API_KEY"},
    json={"isActive": True, "expectedVersion": 3},
)

Respuesta 200

{
  "success": true,
  "message": "Flow actualizado",
  "data": {
    "id": "flow_ab12cd34ef",
    "isActive": true,
    "version": 4,
    "updatedAt": "2026-06-18T10:00:00.000Z"
  }
}

Respuesta 409 — versión desactualizada

{
  "success": false,
  "message": "El flujo fue modificado por otro usuario (versión actual: 5).",
  "currentVersion": 5
}

Validar flujo

GET /workspaces/:workspaceId/flows/:flowId/validate Copiar

Corre las mismas reglas de estructura que bloquean guardar/activar en el editor (nodos huérfanos, trigger faltante, campos requeridos sin llenar, ciclos no permitidos, etc.), sin modificar el flujo.

cURL

curl "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/FLOW_ID/validate" \
  -H "Authorization: Bearer TU_API_KEY"

Node

const res = await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/flows/FLOW_ID/validate',
  { headers: { Authorization: 'Bearer TU_API_KEY' } }
);

const { data } = await res.json();

Python

import requests

res = requests.get(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/FLOW_ID/validate",
    headers={"Authorization": "Bearer TU_API_KEY"},
)

result = res.json()["data"]

Respuesta 200

{
  "success": true,
  "message": "Flow con errores",
  "data": {
    "valid": false,
    "errors": ["El nodo \"Enviar WhatsApp\" no tiene un template configurado"],
    "warnings": ["El nodo \"Condición\" tiene una rama sin conectar"]
  }
}

Disparar manualmente

POST /workspaces/:workspaceId/flows/:flowId/trigger Copiar

Crea una ejecución y corre el flujo en segundo plano — la respuesta llega de inmediato con el executionId, sin esperar a que termine. Consulta el resultado con detalle de ejecución. Requiere la capability flows:execute.

Cuerpo de la petición

Campo	Tipo	Requerido	Descripción
triggerData	object	No	Datos disponibles en el flujo como {{triggerData.<campo>}}.
startNodeId	string	No	Ejecutar desde un nodo concreto en vez de desde el trigger (“Ejecutar desde aquí” del editor).

cURL

curl -X POST "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/FLOW_ID/trigger" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "triggerData": { "email": "ana@empresa.com", "plan": "pro" } }'

Node

const res = await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/flows/FLOW_ID/trigger',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer TU_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      triggerData: { email: 'ana@empresa.com', plan: 'pro' },
    }),
  }
);

const { data } = await res.json();

Python

import requests

res = requests.post(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/FLOW_ID/trigger",
    headers={"Authorization": "Bearer TU_API_KEY"},
    json={"triggerData": {"email": "ana@empresa.com", "plan": "pro"}},
)

execution = res.json()["data"]

Respuesta 201

{
  "success": true,
  "message": "Ejecución iniciada",
  "data": {
    "executionId": "exec_ab12cd34ef",
    "flowId": "flow_ab12cd34ef",
    "status": "running",
    "startedAt": "2026-06-18T09:00:00.000Z"
  }
}

Regenerar token de webhook

POST /workspaces/:workspaceId/flows/:flowId/regenerate-token Copiar

Invalida el token de webhook actual y genera uno nuevo. Solo aplica a flujos con triggerType: "webhook" — en cualquier otro caso responde 400. El token anterior deja de funcionar de inmediato.

cURL

curl -X POST "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/FLOW_ID/regenerate-token" \
  -H "Authorization: Bearer TU_API_KEY"

Node

const res = await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/flows/FLOW_ID/regenerate-token',
  { method: 'POST', headers: { Authorization: 'Bearer TU_API_KEY' } }
);

const { data } = await res.json();

Python

import requests

res = requests.post(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/FLOW_ID/regenerate-token",
    headers={"Authorization": "Bearer TU_API_KEY"},
)

result = res.json()["data"]

Respuesta 201

{
  "success": true,
  "message": "Token regenerado",
  "data": {
    "id": "flow_ab12cd34ef",
    "webhookToken": "wh_9f3a1c7b2e4d5a6f"
  }
}

Crear carpeta

POST /workspaces/:workspaceId/flows/folders Copiar

Cuerpo de la petición

Campo	Tipo	Requerido	Descripción
name	string	Sí	Nombre de la carpeta.
parentId	string	No	Carpeta padre, para anidar.

Consejo

Al eliminar una carpeta, los flujos que contenía no se borran: quedan con folderId: null (sin carpeta).

cURL

curl -X POST "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/folders" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Onboarding" }'

Node

await fetch('https://api.waiify.com/workspaces/WORKSPACE_ID/flows/folders', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer TU_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Onboarding' }),
});

Python

import requests

requests.post(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/folders",
    headers={"Authorization": "Bearer TU_API_KEY"},
    json={"name": "Onboarding"},
)

Respuesta 201

{
  "success": true,
  "message": "Carpeta creada",
  "data": {
    "id": "folder_ab12cd34ef",
    "workspaceId": "ws_ab12cd34ef",
    "name": "Onboarding",
    "parentId": null,
    "createdAt": "2026-06-18T09:00:00.000Z"
  }
}

Crear secret (Bóveda)

POST /workspaces/:workspaceId/flows/secrets Copiar

Requiere ser OWNER del workspace o tener la capability boveda:manage. El valor viaja en texto plano solo en esta petición: se guarda cifrado (AES-256-GCM) y ninguna respuesta posterior lo vuelve a exponer completo — solo un preview con los últimos 4 caracteres.

Cuerpo de la petición

Campo	Tipo	Requerido	Descripción
name	string	Sí	Nombre único en el workspace. Se referencia como {{boveda.name}}.
value	string	Sí	Valor a cifrar (API key, token, etc.).
description	string	No	Descripción.
flowId	string	No	Si se envía, el secret solo queda disponible dentro de ese flujo; si se omite, es global al workspace.

cURL

curl -X POST "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/secrets" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "stripe_api_key", "value": "sk_live_xxxxxxxxxxxx" }'

Node

await fetch('https://api.waiify.com/workspaces/WORKSPACE_ID/flows/secrets', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer TU_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'stripe_api_key', value: 'sk_live_xxxxxxxxxxxx' }),
});

Python

import requests

requests.post(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/secrets",
    headers={"Authorization": "Bearer TU_API_KEY"},
    json={"name": "stripe_api_key", "value": "sk_live_xxxxxxxxxxxx"},
)

Respuesta 201

{
  "success": true,
  "message": "Secret creado",
  "data": {
    "id": "secret_ab12cd34ef",
    "name": "stripe_api_key",
    "description": null,
    "flowId": null,
    "preview": "••••••xxxx",
    "createdAt": "2026-06-18T09:00:00.000Z"
  }
}

Crear variable global

POST /workspaces/:workspaceId/flows/global-vars Copiar

A diferencia de la Bóveda, cualquier miembro del workspace puede crear/editar/borrar variables globales: valor en texto plano, pensado para datos no sensibles compartidos entre flujos (un ID de catálogo, una URL base, un nombre de sucursal).

Cuerpo de la petición

Campo	Tipo	Requerido	Descripción
name	string	Sí	Identificador válido (letras, números, guion bajo). Se referencia como {{globalVars.name}}.
value	string	Sí	Valor de la variable.
description	string	No	Descripción.

cURL

curl -X POST "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/global-vars" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "sucursal_principal", "value": "CDMX Centro" }'

Node

await fetch('https://api.waiify.com/workspaces/WORKSPACE_ID/flows/global-vars', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer TU_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'sucursal_principal', value: 'CDMX Centro' }),
});

Python

import requests

requests.post(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/global-vars",
    headers={"Authorization": "Bearer TU_API_KEY"},
    json={"name": "sucursal_principal", "value": "CDMX Centro"},
)

Respuesta 201

{
  "success": true,
  "message": "Variable creada",
  "data": {
    "id": "gvar_ab12cd34ef",
    "workspaceId": "ws_ab12cd34ef",
    "name": "sucursal_principal",
    "value": "CDMX Centro",
    "description": null,
    "createdAt": "2026-06-18T09:00:00.000Z"
  }
}

Listar ejecuciones de un flujo

GET /workspaces/:workspaceId/flows/:flowId/executions Copiar

Parámetros de query

Parámetro	Tipo	Descripción
status	string	running, completed, failed o cancelled.
trigger	string	manual, webhook, schedule, ai_tool, simulation, crm_event o voice_call.
page / limit	number	Ver paginación.

Consejo

Para ver las ejecuciones de todo el workspace (sin filtrar por flujo), usa GET /workspaces/:workspaceId/flows/executions con los filtros flowId, status, dateFrom, dateTo y search.

cURL

curl "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/FLOW_ID/executions?status=failed&page=1&limit=20" \
  -H "Authorization: Bearer TU_API_KEY"

Node

const res = await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/flows/FLOW_ID/executions?status=failed',
  { headers: { Authorization: 'Bearer TU_API_KEY' } }
);

const { data: executions } = await res.json();

Python

import requests

res = requests.get(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/FLOW_ID/executions",
    headers={"Authorization": "Bearer TU_API_KEY"},
    params={"status": "failed", "page": 1, "limit": 20},
)

executions = res.json()["data"]

Respuesta 200

{
  "success": true,
  "data": [
    {
      "id": "exec_ab12cd34ef",
      "flowId": "flow_ab12cd34ef",
      "status": "failed",
      "trigger": "webhook",
      "durationMs": 842,
      "errorMsg": "El nodo \"HTTP Request\" respondió 500",
      "startedAt": "2026-06-18T09:00:00.000Z",
      "completedAt": "2026-06-18T09:00:01.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}

Obtener detalle de una ejecución

GET /workspaces/:workspaceId/flows/executions/:executionId Copiar

Incluye steps: el registro de cada nodo por el que pasó la ejecución, con su input/output y logs — lo que pinta el panel de depuración del editor.

cURL

curl "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/executions/EXECUTION_ID" \
  -H "Authorization: Bearer TU_API_KEY"

Node

const res = await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/flows/executions/EXECUTION_ID',
  { headers: { Authorization: 'Bearer TU_API_KEY' } }
);

const { data: execution } = await res.json();

Python

import requests

res = requests.get(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/executions/EXECUTION_ID",
    headers={"Authorization": "Bearer TU_API_KEY"},
)

execution = res.json()["data"]

Respuesta 200

{
  "success": true,
  "data": {
    "id": "exec_ab12cd34ef",
    "flowId": "flow_ab12cd34ef",
    "workspaceId": "ws_ab12cd34ef",
    "status": "completed",
    "trigger": "manual",
    "triggerData": { "email": "ana@empresa.com" },
    "result": { "sent": true },
    "durationMs": 1240,
    "errorMsg": null,
    "startedAt": "2026-06-18T09:00:00.000Z",
    "completedAt": "2026-06-18T09:00:01.240Z",
    "flow": { "id": "flow_ab12cd34ef", "name": "Bienvenida a nuevos leads" },
    "steps": [
      {
        "nodeId": "node_1",
        "nodeType": "action.whatsapp_send",
        "nodeLabel": "Enviar WhatsApp",
        "status": "completed",
        "input": { "to": "+5215555555555" },
        "output": { "messageId": "wamid.xxx" },
        "startedAt": "2026-06-18T09:00:00.100Z",
        "completedAt": "2026-06-18T09:00:01.200Z",
        "durationMs": 1100
      }
    ]
  }
}

Cancelar ejecución

POST /workspaces/:workspaceId/flows/executions/:executionId/cancel Copiar

Solo se puede cancelar una ejecución en estado running; en cualquier otro estado responde 400.

cURL

curl -X POST "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/executions/EXECUTION_ID/cancel" \
  -H "Authorization: Bearer TU_API_KEY"

Node

await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/flows/executions/EXECUTION_ID/cancel',
  { method: 'POST', headers: { Authorization: 'Bearer TU_API_KEY' } }
);

Python

import requests

requests.post(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/flows/executions/EXECUTION_ID/cancel",
    headers={"Authorization": "Bearer TU_API_KEY"},
)

Respuesta 200

{
  "success": true,
  "message": "Ejecución cancelada correctamente"
}

Respuesta 400 — ya no está en curso

{
  "success": false,
  "message": "Solo se pueden cancelar ejecuciones en progreso"
}

Disparar por webhook (público)

Un flujo con trigger webhook se dispara con su token, sin API key. Ver la referencia completa en Webhooks.

POST /flows/run?token=WEBHOOK_TOKEN Copiar

Parámetros de query

Parámetro	Tipo	Descripción
token	string	Token del webhook del flujo (webhookToken).

El cuerpo (JSON) queda disponible en el flujo como {{triggerData.<campo>}}.

cURL

curl -X POST "https://api.waiify.com/flows/run?token=WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ana@empresa.com", "plan": "pro" }'

Node

await fetch('https://api.waiify.com/flows/run?token=WEBHOOK_TOKEN', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'ana@empresa.com', plan: 'pro' }),
});

Python

import requests

requests.post(
    "https://api.waiify.com/flows/run",
    params={"token": "WEBHOOK_TOKEN"},
    json={"email": "ana@empresa.com", "plan": "pro"},
)

Respuesta 201

{
  "success": true,
  "message": "Ejecución iniciada",
  "data": {
    "executionId": "exec_ab12cd34ef",
    "status": "running",
    "startedAt": "2026-06-18T09:00:00.000Z"
  }
}

Si falta un parámetro requerido por el nodo trigger, la API responde 400 con { "success": false, "message": "...", "missing": ["campo"] } en vez de ejecutar el flujo.

Relacionado

• Bases de datos · Webhooks · Bóveda (secrets)