OpenFunnel DocsRepositorio ↗

Documentación del proyecto

En esta página

API para agentes externos#

La API permite leer recursos, crear/configurar agentes y prompts, asignarlos a canales con IA desactivada y probarlos. Las herramientas nativas están disponibles automáticamente. Una clave no permite enviar mensajes, borrar registros, activar canales ni editar herramientas. En cloud cada clave pertenece a un espacio aislado. Usar HTTPS en producción. HTTP se reserva al desarrollo en loopback.

Crear una clave#

En Configuración → Claves API, indica nombre, vencimiento (1–365 días) y permisos:

Permiso Operaciones
resources:read GET de recursos y versiones de prompts.
prompts:write POST para crear prompts, PATCH para editarlos y POST para restaurar versiones.
agents:write POST de agentes y PATCH de configuración, prompt_ids y tool_ids.
channels:assign PUT /api/channels/ID_CANAL/agent: asignar agente con la IA del canal desactivada.
agents:test POST de una prueba aislada del agente.

Los permisos son independientes. Para leer y corregir un prompt selecciona los dos primeros. Para preparar agentes selecciona también agents:write y channels:assign. Las claves existentes no reciben permisos nuevos: crea otra con los permisos necesarios y revoca la anterior cuando dejes de usarla. Guarda el secreto cuando se muestra: después solo aparece su prefijo. La base conserva su hash. Revocar impide nuevas solicitudes inmediatamente; para rotar, crea otra clave y revoca la anterior. Vencimiento y último uso aparecen en la lista. No pegues claves en prompts ni las publiques en clientes web. Máximo 100 claves conservadas en esta entrega; revocar no borra el registro.

Autenticación: Authorization: Bearer <CLAVE>, sin cookie. Mezclar ambos mecanismos se rechaza; un Bearer inválido no recurre a una sesión válida. Crear/listar/revocar claves requiere sesión del usuario del espacio (administrador en self-hosted) y protección de origen en las mutaciones.

En cloud añade X-OpenFunnel-Workspace: ID_ESPACIO en todas las solicitudes con Bearer. El ID aparece en la página de Claves API. En self-hosted se omite. La clave se valida dentro de ese espacio; cambiar el ID no concede acceso a otra cuenta. Los ejemplos curl siguientes omiten ese header por brevedad; añádelo en cloud.

Leer recursos#

Los ejemplos son ilustrativos y usan identificadores de muestra:

curl 'https://TU_INSTANCIA/api/conversations?page=1&pageSize=25' \
  -H 'Authorization: Bearer <CLAVE>'
curl 'https://TU_INSTANCIA/api/messages?conversation_id=ID_CONVERSACION&page=1&pageSize=25' \
  -H 'Authorization: Bearer <CLAVE>'
curl 'https://TU_INSTANCIA/api/ai_agents/ID_AGENTE' \
  -H 'Authorization: Bearer <CLAVE>'

Recursos: contacts, conversations, messages, tickets, ai_agents, prompts, tools, channels, pipelines, pipeline_stages y users. GET /api/RECURSO/ID devuelve un registro. Los listados devuelven {items,total,page,pageSize}: 25 por página de forma predeterminada, máximo 100. q busca según el recurso; filtros permitidos en shared/resources.js. Las conversaciones admiten channel_id y los mensajes conversation_id. Filtros desconocidos se rechazan.

Crear y conectar un agente#

Este ejemplo para Node.js 24 usa únicamente una API key. Define OPENFUNNEL_URL, OPENFUNNEL_API_KEY, OPENFUNNEL_CHANNEL_ID (un canal Zernio ya conectado) y, en cloud, OPENFUNNEL_WORKSPACE_ID. No utiliza usuario, contraseña ni cookie de login. La clave necesita resources:read, prompts:write, agents:write y channels:assign.

const base = process.env.OPENFUNNEL_URL.replace(/\/$/, '');
const headers = {
  Authorization: `Bearer ${process.env.OPENFUNNEL_API_KEY}`,
  'Content-Type': 'application/json',
  ...(process.env.OPENFUNNEL_WORKSPACE_ID
    ? { 'X-OpenFunnel-Workspace': process.env.OPENFUNNEL_WORKSPACE_ID } : {}),
};
async function request(method, path, body) {
  const response = await fetch(`${base}/api${path}`, {
    method, headers,
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
  });
  const data = await response.json();
  if (!response.ok) throw new Error(`${response.status}: ${data.error}`);
  return data;
}
const prompt = await request('POST', '/prompts', {
  name: 'Atención al cliente',
  content: 'Responde brevemente. Si solicitan una persona, usa handoff_to_human con el motivo.',
});
const handoff = await request('GET', '/tools/builtin_handoff_to_human');
const agent = await request('POST', '/ai_agents', {
  name: 'Asistente', active: true,
  prompt_ids: [prompt.id], tool_ids: [handoff.id],
});
await request('PUT', `/channels/${process.env.OPENFUNNEL_CHANNEL_ID}/agent`, {
  agent_id: agent.id,
});
console.log({ agentId: agent.id, promptId: prompt.id, automationEnabled: false });

POST devuelve 201 con el recurso creado. Para un agente existente utiliza PATCH /api/ai_agents/ID_AGENTE con prompt_ids y/o tool_ids: cada array reemplaza esa selección; las propiedades omitidas se conservan. Se rechazan referencias inexistentes o de otras cuentas. POST no es idempotente: conserva los IDs devueltos y consulta antes de repetir una creación tras una respuesta incierta.

PUT /api/channels/ID_CANAL/agent acepta exclusivamente {agent_id} y devuelve {ok:true}. Guarda default_ai_agent_id, deja automation_enabled:0 e invalida trabajo pendiente. También desactiva un canal que ya tenía IA encendida. No llama al proveedor, conecta una cuenta Zernio ni cambia el agente específico de conversaciones que ya tenían uno asignado. Revisa la configuración y activa la IA desde la UI cuando corresponda; active:true en el agente no activa el canal. No se admite enabled en este endpoint. Crear/configurar recursos no consume créditos; probar o ejecutar IA conserva los requisitos de proveedor, plan y saldo de la instancia.

Herramientas nativas#

No es necesario crear herramientas. Cada espacio dispone de:

ID estable Función Comportamiento
builtin_get_contact get_contact Lee el contacto de la conversación actual.
builtin_get_ticket get_ticket Lee el ticket de la conversación actual.
builtin_handoff_to_human handoff_to_human Recibe reason, pausa la IA de esa conversación y guarda el motivo.

Se seleccionan en Agentes IA → agente → Herramientas o mediante tool_ids. No se añaden automáticamente a los agentes. Las definiciones y su ejecución pertenecen al backend: /api/tools solo permite GET, incluso con sesión. Los registros heredados y sus asociaciones se conservan; las nuevas opciones de la UI son las nativas.

La derivación cambia la conversación a modo manual y cancela ejecuciones y envíos IA pendientes. No envía un mensaje, no pausa otros chats y no reanuda automáticamente al recibir otro mensaje: una persona debe retomar la conversación o reactivar su IA. El modo Probar simula la derivación sin modificar conversaciones.

Editar y restaurar prompts#

Lee primero GET /api/prompts/ID_PROMPT y utiliza su version como expected_version. PATCH acepta nombre, descripción, contenido y estado activo. El resto se conserva. Cada guardado crea una versión con autor y fecha.

curl -X PATCH 'https://TU_INSTANCIA/api/prompts/ID_PROMPT' \
  -H 'Authorization: Bearer <CLAVE>' -H 'Content-Type: application/json' \
  -d '{"expected_version":1,"content":"Responde brevemente y pide aclaración si faltan datos."}'

GET /api/prompts/ID_PROMPT/versions?page=1 devuelve 20 versiones por página, current_version, agentes afectados, total y paginación. Restaurar recupera nombre, descripción, contenido y estado activo como una nueva versión:

curl -X POST 'https://TU_INSTANCIA/api/prompts/ID_PROMPT/restore' \
  -H 'Authorization: Bearer <CLAVE>' -H 'Content-Type: application/json' \
  -d '{"version":1,"expected_version":2}'

Si la versión de partida ya no es actual se devuelve 409: vuelve a leer y revisa los cambios antes de reintentar. No repitas automáticamente con la nueva versión. Un reintento del mismo PATCH con la versión vieja no crea otra revisión. Los prompts compartidos afectan a todos sus agentes; la UI muestra las asociaciones. Cambiar la configuración invalida resultados IA pendientes en la siguiente revalidación, pero no puede deshacer un envío ya aceptado por el proveedor. Un hilo cancelado puede requerir revisión y reanudación humana, conforme al runtime existente.

Documentos de conocimiento#

En Agentes IA → agente → Conocimiento, sube TXT/MD UTF-8, DOC, DOCX o PDF con texto: 5 MiB por archivo, 10 documentos y 30000 caracteres disponibles por agente. El original se conserva como BLOB en SQLite junto con su texto extraído, nombre, tamaño, revisión, fecha y estado. No hay Base64, OCR, RAG ni embeddings.

Con resources:read puedes consultar:

Las mutaciones requieren sesión del administrador y Origin, nunca una API key. POST a la colección carga un archivo; PUT al documento lo reemplaza. Ambos utilizan Content-Type: application/octet-stream, X-Filename con nombre codificado mediante encodeURIComponent y el binario crudo como cuerpo. No usar JSON ni Base64. PUT y DELETE al documento exigen If-Match: 1 con su revisión actual. Si cambió, se devuelve 409 sin sobrescribir. DELETE elimina original y texto.

Una carga nueva devuelve 201 con status: ready o status: error; comprueba el estado, ya que el original se conserva aunque la extracción falle. Los estados processing aparecen en la lista mientras trabaja el servidor. Un reemplazo fallido devuelve error y conserva intacto el documento anterior. Los límites por agente incluyen archivos con error en el conteo, pero solo texto disponible en el presupuesto.

La extracción ocurre una vez por carga. El texto disponible se incluye en cada llamada al modelo como referencia separada de instrucciones; consume tokens de cada solicitud. Los valores legacy business_context se migran a contexto-inicial.txt. business_context, provider y model ya no son campos editables de agentes. El proveedor y modelo se configuran para el espacio desde Agentes IA → Configurar proveedor, o mediante LLM_BASE_URL, LLM_API_KEY y LLM_MODEL del servidor. Las API keys de OpenFunnel no pueden leer ni modificar esas credenciales.

Probar un agente#

Desde el detalle del agente, abre Probar y escribe un mensaje. Opcionalmente ensaya otras instrucciones sin guardarlas. Por API, requiere agents:test:

curl -X POST 'https://TU_INSTANCIA/api/ai_agents/ID_AGENTE/test' \
  -H 'Authorization: Bearer <CLAVE>' -H 'Content-Type: application/json' \
  -d '{"message":"¿Cuándo atienden?","prompt":"Responde usando los horarios del negocio."}'

message admite 4000 caracteres. prompt es opcional, hasta 20000 caracteres, y sustituye todos los prompts activos solo durante esa prueba. Si se omite, se usan los prompts activos ordenados (máximo combinado 30000 caracteres). El contexto y las herramientas provienen del agente guardado. No se exige que esté activo ni que su modelo esté validado para operación, pero sí un proveedor/modelo configurado.

Devuelve response, tools simuladas, usage (null si no se informó), duration_ms, simulated, candidate y versiones de prompts usadas cuando no hay candidato. Todas las tools se simulan: contacto/ticket devuelven ausencia de datos reales y la derivación humana no cambia el modo de ninguna conversación. No se guardan pruebas, mensajes ni ejecuciones operativas. La prueba sí llama al modelo y consume tokens. No reproduce el historial de una conversación operativa ni demuestra entrega real a un canal.

Para continuar una prueba envía history, un array alternado de objetos {role:"user"|"assistant",content:"..."}, y el context_hash de la respuesta anterior. Incluye el mismo candidato prompt, si lo usaste. Máximo 20 mensajes previos y 18000 caracteres combinados; no se admiten roles system/tool ni campos adicionales. Cada respuesta incluye documents (id, filename, revision) y context_hash. Si cambia la configuración, documentos o candidato, devuelve 409 y debes reiniciar con historial vacío. El cliente conserva el historial: el servidor no lo persiste.

Límites y errores#

Las claves y versiones persisten en SQLite mediante la migraciones aditivas 005/006. El historial dura mientras exista el prompt; eliminar un prompt sin referencias elimina también sus versiones. El sistema mantiene las restricciones de borrado existentes.

Instrucciones directamente desde el agente#

GET /api/ai_agents/:id/instructions requiere resources:read y devuelve el agente, los prompts en orden, sus versiones y los agentes que los comparten. PUT en la misma ruta requiere ambos scopes agents:write y prompts:write. El cuerpo contiene expected_ids (IDs asociados leídos, en orden) y prompts con { id, expected_version, content } por prompt. El conjunto se guarda atómicamente; 409 conserva el servidor sin cambios cuando una versión o asociación cambió. Si el agente todavía no tiene prompts, usar expected_ids: [] y prompts: [{ content: "Instrucciones iniciales" }]: crea y asocia uno en la misma transacción. No modifica orden, activación ni herramientas de prompts existentes.