Lia System — API Reference (1.0.0)

Devuelve la lista mínima de agentes del usuario autenticado, ordenados alfabéticamente. Útil para llenar selectores y dropdowns en la UI. Si necesitas todos los campos del agente, usa /agents/full.

Crea un nuevo agente conversacional. Solo name es obligatorio; el resto de campos toman valores por defecto sensatos (modelo gpt-4o-mini, ventana de memoria de 10 mensajes, sin permisos de imagen ni voz).

Puedes asignar canales al momento de la creación pasando un array de IDs en assigned_channels.

Devuelve la lista completa de agentes del usuario con todos sus campos (prompt, modelo, configuración de acciones, etc.), ordenados por fecha de creación descendente. Úsalo en la página de gestión de agentes.

Actualiza parcialmente un agente. Solo se modifican los campos enviados en el body (PATCH). Si pasas assigned_channels, se reemplaza la asignación completa de canales del agente.

Elimina permanentemente un agente y desasigna sus canales. Las conversaciones existentes quedan huérfanas (sin agente) y dejarán de recibir respuestas automáticas.

Activa o pausa un agente sin eliminarlo. Cuando un agente está inactivo deja de responder mensajes entrantes, pero conserva su configuración y conversaciones.

Marca este agente como el principal del usuario. El agente primario se usa por defecto cuando una conversación no tiene un agente asignado explícitamente. Solo puede haber un primario a la vez.

Lista paginada de contactos del usuario. Soporta búsqueda por nombre o teléfono y múltiples filtros combinables: plataforma, agente, tags, rangos de fecha y custom fields.

Las peticiones sin filtros están cacheadas en Redis por 30 segundos para mejorar el rendimiento. Usa DELETE /contacts/cache para forzar invalidación tras una mutación masiva externa.

Crea un nuevo contacto asociado a un agente. El par (agent_id, phone_number) debe ser único — si ya existe se devuelve un 409 Conflict.

Esta acción dispara automáticamente las automatizaciones con trigger contact_created configuradas para ese agente.

Importa hasta 100 contactos en una sola petición. Por defecto, los teléfonos duplicados se omiten silenciosamente (skip_duplicates: true) y las automatizaciones de contact_created se disparan (fire_automations: true).

La respuesta incluye conteos de insertados, omitidos y errores individuales para que puedas reconciliar lotes grandes.

Invalida el caché Redis de listados de contactos del usuario. Útil después de mutaciones realizadas fuera de la API (por ejemplo, importaciones desde la base de datos directamente).

Actualiza parcialmente la información personal de un contacto (nombre, email, ciudad, dirección, fecha de nacimiento). El número de teléfono y el agente asociado no son modificables por esta vía.

Elimina permanentemente un contacto y todas sus conversaciones, mensajes y tags asociados. Esta acción no se puede deshacer.

Devuelve todas las conversaciones del usuario con datos enriquecidos: información del contacto, tags asignados, último mensaje y timestamp. Pensado para alimentar la lista lateral del inbox.

El resultado se cachea en Redis por 5 segundos para reducir carga en peticiones frecuentes.

Devuelve los últimos 100 mensajes de una conversación ordenados cronológicamente (más antiguo primero). Incluye contenido, multimedia, rol (user o assistant) y metadata.

Envía un mensaje manual al contacto desde la cuenta del agente. Permite texto plano, multimedia (imagen, video, documento, audio) o ambos combinados.

Los mensajes manuales se guardan en el historial pero no se consideran respuestas de la IA. Útil para intervención humana en hilos donde la IA está pausada.

Activa o pausa la IA para una conversación específica. Cuando está pausada, los mensajes entrantes se siguen guardando pero no generan respuestas automáticas — ideal para tomar control humano de un hilo.

Realiza un corte de contexto: el historial sigue visible en el inbox pero la IA olvidará todos los mensajes anteriores al corte para sus próximas respuestas. Útil cuando el contacto cambia de tema o sesión sin necesidad de borrar la conversación.

Elimina permanentemente la conversación y todos sus mensajes. El contacto y sus tags permanecen. Esta acción no se puede deshacer.

Devuelve todos los canales conectados del usuario, incluyendo plataforma, nombre visible, estado de conexión y fecha de creación. Cubre todas las plataformas soportadas en una sola respuesta.

Conecta un bot de Telegram a Lia System usando el token que obtienes al crear el bot con @BotFather. El sistema valida el token contra la API de Telegram antes de guardarlo.

Desconecta un bot de Telegram. El bot deja de recibir mensajes en Lia System pero sigue activo en Telegram — debes desactivarlo desde BotFather si quieres apagarlo del todo.

Lista los números de WhatsApp conectados manualmente vía API key (en lugar de OAuth/Embedded Signup). Cada número incluye su estado y nombre visible.

Conecta un número de WhatsApp Business API usando una API key manual. Útil cuando ya tienes un proveedor de WhatsApp Business y quieres integrarlo sin pasar por el flujo de Embedded Signup.

Elimina un número de WhatsApp manual. El número deja de procesar mensajes inmediatamente.

Endpoint consolidado que devuelve todo lo necesario para renderizar la página de automatizaciones: lista de flujos, agentes disponibles y metadatos relacionados. Reduce el número de round-trips desde el frontend.

Devuelve el detalle completo de una automatización: nodos, aristas, trigger y configuración. Úsalo al abrir el editor de flujos.

Crea una nueva automatización en estado inactivo por defecto. El cuerpo acepta los nodos y aristas iniciales del flujo, o puedes crearla vacía y editarla después.

Actualiza parcialmente una automatización. Usa este endpoint para guardar cambios desde el editor visual o para activar/desactivar flujos sin reescribir su estructura.

Elimina permanentemente una automatización. Las ejecuciones en curso se cancelan; las ejecuciones futuras no se dispararán.

Dispara una automatización manualmente con datos custom en lugar de esperar a su trigger natural. Útil para pruebas o para ejecuciones programadas desde sistemas externos.

Envía un mensaje de texto desde un nodo de automatización al número especificado, usando la cuenta del agente indicado. Es la acción base de los nodos "Enviar mensaje".

Devuelve todos los templates de WhatsApp del usuario con su estado de aprobación (PENDING, APPROVED, REJECTED), categoría e idioma.

Crea un nuevo template y lo envía a Meta para revisión. La aprobación toma típicamente de minutos a 24 horas. El template no se puede usar hasta que Meta lo apruebe.

Categorías válidas:

• MARKETING — promocional
• UTILITY — transaccional / actualizaciones
• AUTHENTICATION — códigos OTP

Devuelve el detalle completo de un template, incluyendo sus componentes (header, body, footer, buttons) y estado actual.

Actualiza un template existente. Cualquier cambio significativo re-envía el template a Meta para nueva aprobación, durante la cual el template no se puede usar.

Elimina un template tanto en Lia System como en Meta. Una vez eliminado, no se puede recuperar; tendrías que crear uno nuevo y volver a pasar por revisión.

Crea una copia de un template existente con un nuevo nombre. La copia se envía a Meta para nueva aprobación de forma independiente.

Sincroniza los templates con el proveedor de WhatsApp. Útil cuando Meta cambia el estado de un template (aprobado/rechazado) y quieres reflejar el cambio inmediatamente sin esperar al webhook.

Lista todas las bases de conocimiento del usuario. Una base de conocimiento puede asignarse a uno o varios agentes.

Crea una base de conocimiento vacía. Después debes agregarle fuentes (texto, URLs o archivos) usando POST /knowledge-bases/{id}/sources.

Devuelve los metadatos de una base de conocimiento. Para obtener sus fuentes usa el endpoint /sources.

Actualiza nombre y descripción de una base de conocimiento. No afecta sus fuentes ni embeddings ya generados.

Elimina permanentemente una base de conocimiento, sus fuentes y todos los embeddings asociados. Los agentes que la usaban pierden el acceso a ese contexto.

Lista todas las fuentes de una base de conocimiento, con su tipo (text, url, file) y estado de procesamiento (pendiente, embeddeado, error).

Agrega una nueva fuente a la base. El procesamiento de embeddings se encola en segundo plano — la fuente queda disponible para los agentes cuando su estado pasa a embedded.

Actualiza el contenido o URL de una fuente. Modificar el contenido re-encola los embeddings; durante el reprocesamiento la fuente queda marcada como pendiente.

Elimina una fuente y sus embeddings asociados. Los agentes ya no podrán recuperar contexto desde esa fuente en sus respuestas.