Crear Agente

POST /workflows Crea un agente nuevo (funnel + statuses) desde cero — completamente vía API. Este es el primer paso del ciclo de vida API-first de un agente:

Crear el agente (este endpoint). Nace pausado.
Configurar su prompt — qué dice y cómo se comporta.
Opcionalmente agregar statuses/campos personalizados o tools personalizadas que pueda llamar.
Activarlo seteando is_paused: false.

Idempotente. Si ya existe un agente con el mismo name en tu cuenta, devuelve el existente (status: "existed") en lugar de crear un duplicado — seguro de reintentar.

Cuerpo de la Solicitud

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre del agente. Se usa para el chequeo de idempotencia
`goal_type`	string	Sí	Uno de los valores de la tabla Goals disponibles
`statuses`	array	Sí	Array no vacío de statuses del funnel (ver abajo). Si ninguno está marcado `is_initial`, se usa el primero; si ninguno está marcado `is_terminal`, se usa el último
`description`	string	No	Descripción del agente
`global_prompt`	string	No	Prompt base. También se puede configurar después vía `PATCH /workflows/:id/prompt`
`language`	string	No	Por defecto `es`
`channels`	array	No	Canales a habilitar, ej. `["whatsapp", "email"]`. Por defecto `["whatsapp"]`
`fields`	array	No	Campos personalizados a recolectar (ver Actualizar Estructura para la forma exacta)

Goals disponibles

`goal_type`	Resultado esperado	Notas
`appointment`	Agendar una reunión	Habilita las capacidades de calendario.
`payment_link`	Enviar un link de pago y cerrar el cobro	La integración que genera o entrega el link debe estar configurada.
`qualification`	Calificar al lead según los datos recopilados	Combínalo con campos y etapas que expresen los criterios.
`information`	Responder preguntas	Normalmente depende de una base de conocimiento.
`support`	Resolver o escalar consultas de soporte	Define reglas claras de escalación.
`document_collection`	Solicitar y verificar documentos	El dashboard muestra una sección Documentos para este goal.
`quote`	Generar una cotización desde un catálogo	Requiere un catálogo asignado.
`custom`	Cumplir un objetivo escrito por el operador	No habilita herramientas de calendario.
`sale`	Completar una venta	Valor compatible con la API; no aparece como preset en el selector actual del dashboard.

El onboarding también muestra Calificar y luego agendar. Esa opción se guarda como appointment con un pipeline y reglas de calificación; no envíes qualify_then_book a este endpoint público.

El goal `custom`

Usa custom cuando el objetivo del agente no es ninguno de los presets: cobranza, reactivación de clientes, post-venta o encuestas. El agente persigue un objetivo escrito en tus propias palabras, configurado en el Dashboard en Configuración del agente → Objetivo y guardado como config.goal_statement. Admite hasta 600 caracteres y debe describir el resultado, no el procedimiento. Dos cosas a saber:

Un agente custom no agenda reuniones — las herramientas de calendario no están disponibles para él. Si el objetivo termina en una reunión agendada, usa appointment.
Debes enviar statuses como en cualquier otro goal. Este endpoint no infiere el pipeline; para un custom típico puedes usar new → contacted → engaged → converted → lost y adaptar las instrucciones de transición al resultado escrito.

Forma de `statuses[]`

Campo	Tipo	Requerido	Descripción
`key`	string	Sí	Identificador estable del status
`name`	string	Sí	Etiqueta visible (`label` también es aceptado)
`is_initial`	boolean	No	Marca el status de entrada del funnel
`is_terminal`	boolean	No	Marca un status de cierre del funnel
`sort_order`	integer	No	Por defecto, el índice del array

Respuestas

`201` — Agente creado

{
  "success": true,
  "workflow_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "created"
}

`200` — Ya existía (respuesta idempotente)

{
  "success": true,
  "workflow_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "existed"
}

`400` — Error de validación

{
  "error": "Invalid input",
  "message": "name is required"
}

Otros errores de validación:

"goal_type must be one of: appointment, sale, qualification, information, payment_link, support, custom, quote, document_collection"
"statuses must be a non-empty array"
"each status needs a key and a name"

`401` — Error de autenticación

Ver Autenticación.

Quick Start

WhatsApp

Agentes

Asistente

Avanzado

Referencia API

Leads

Agentes

Workflow Tools

Client Tools

Grupos

Campañas

Conversiones

Reportes

Conversaciones

Tags

Background Jobs

Mensajes

Reuniones

Equipo

Procesadores

Crear Agente

Cuerpo de la Solicitud

Goals disponibles

El goal `custom`

Forma de `statuses[]`

Respuestas

`201` — Agente creado

`200` — Ya existía (respuesta idempotente)

`400` — Error de validación

`401` — Error de autenticación

`500` — Error interno del servidor

​Cuerpo de la Solicitud

​Goals disponibles

​El goal custom

​Forma de statuses[]

​Respuestas

​201 — Agente creado

​200 — Ya existía (respuesta idempotente)

​400 — Error de validación

​401 — Error de autenticación

​500 — Error interno del servidor

Cuerpo de la Solicitud

Goals disponibles

El goal `custom`

Forma de `statuses[]`

Respuestas

`201` — Agente creado

`200` — Ya existía (respuesta idempotente)

`400` — Error de validación

`401` — Error de autenticación

`500` — Error interno del servidor