Ir al contenido

Referencia de API

Asistentes y base de conocimiento

Endpoints para tus asistentes de chat (se abre en una pestaña nueva) y su base de conocimiento (se abre en una pestaña nueva). Todos requieren autenticación (se abre en una pestaña nueva) (API key o sesión) y cuelgan de /workspaces/:workspaceId. Para los agentes de voz y las llamadas, ver Agentes de voz y llamadas (se abre en una pestaña nueva).

MétodoRutaDescripción
GET/agentsListar asistentes
POST/agentsCrear asistente
GET/agents/:idObtener asistente
PATCH/agents/:idActualizar
GET/agents/:id/preflightRevisión antes de activar
DELETE/agents/:idEliminar
POST/agents/:id/duplicateDuplicar (copia toda la configuración, incluido handoff y follow-ups)
POST/agents/:id/widget-logoSubir logo del widget (multipart/form-data, campo logo, imagen, máx. 2 MB)
POST/agents/:id/website/importRastrear una URL y usarla como documento de conocimiento del asistente

Cuelgan de /agents/:id/playground y requieren el permiso assistants:view. Ver Playground (se abre en una pestaña nueva).

MétodoRutaDescripción
POST/agents/:id/playground/sessionsCrear una sesión: contacto y conversación de prueba. Limpia las sesiones anteriores del usuario en ese asistente
GET/agents/:id/playground/sessions/:sessionIdEstado de la conversación (ai, queued, with_advisor, resolved, transferred) y datos del cliente simulado
POST/agents/:id/playground/sessions/:sessionId/resumeReiniciar el estado para que el asistente vuelva a responder
DELETE/agents/:id/playground/sessions/:sessionIdDescartar la sesión y borrar sus datos de prueba

El cuerpo de POST .../sessions es opcional: name (máx. 80), phone (máx. 30), channel (WEB_WIDGET o WHATSAPP, por defecto WEB_WIDGET) y language (es o en, por defecto es). Los datos de prueba no cuentan en métricas, contactos ni facturación.

CampoTipoRequeridoDescripción
namestring (2-60)SíNombre del asistente.
systemPromptstring (10-20 000)SíInstrucciones del asistente.
descriptionstring (máx. 2000)NoDescripción interna.
avatarUrlstringNoURL del avatar.
welcomeMessagestring (máx. 1000)NoMensaje de saludo inicial.
modelstringNoModelo de IA, uno de los habilitados en el catálogo de Waiify (por ejemplo gemini-3.6-flash, gpt-5 o claude-sonnet-5); un modelo que no esté disponible se rechaza. Por defecto gemini-3.6-flash.
languagees | en | multiNoIdioma del asistente (se abre en una pestaña nueva): español, inglés o bilingüe. Por defecto es.
temperaturenúmero (0-2)NoCreatividad de las respuestas. Por defecto 0.7.
maxTokensentero (1-8000)NoTope de tokens de la respuesta. Por defecto 600.
autoCaptureLeadInfobooleanNoCaptura automática de datos del contacto. Por defecto true.
channelsarray de WHATSAPP | WEB_WIDGETNoCanales donde responde. Por defecto ["WEB_WIDGET"].
toolsarray (máx. 50)NoHerramientas del asistente — ver herramientas de asistentes (se abre en una pestaña nueva).
knowledgeDocIdsarray de string (máx. 200)NoDocumentos de conocimiento (se abre en una pestaña nueva) vinculados.
contextIdstringNoID de un contexto de empresa (se abre en una pestaña nueva) existente en el workspace.
widgetColor / widgetBgColorstring (hex)NoColores del widget. Por defecto #2563eb / #0d1424.
widgetPositionleft | rightNoPosición del widget. Por defecto right.
widgetBotName / widgetGreeting / widgetLogoUrlstringNoPersonalización del widget.
POST/workspaces/:workspaceId/agents
PATCH/workspaces/:workspaceId/agents/:id

Acepta los mismos campos que crear (se abre en una pestaña nueva), todos opcionales — es un merge parcial. Además admite:

CampoTipoDescripción
isActivebooleanActiva o desactiva el asistente. Para activarlo debe pasar la revisión antes de activar (se abre en una pestaña nueva); si no, responde 400 con el motivo y el detalle de la revisión.
expectedVersionenteroBloqueo optimista: si no coincide con la versión actual del asistente, rechaza la edición (evita pisar un cambio concurrente). Se omite, no se verifica.
versionLabelstring (máx. 200)Etiqueta para la versión del historial de prompt (se abre en una pestaña nueva) que se autoguarda si systemPrompt cambió.
POST/workspaces/:workspaceId/agents/:id/duplicate

Crea una copia completa del asistente (configuración, prompt por secciones, contexto de empresa, handoff y secuencias de follow-up incluidos), inactiva y con el nombre original + ” (copia)”.

GET/workspaces/:workspaceId/agents/:id/preflight

Devuelve la misma revisión que decide si el asistente se puede activar (ver revisión antes de activar (se abre en una pestaña nueva)). Requiere la capacidad assistants:view.

Respuesta 200
{
"success": true,
"data": {
"ready": false,
"items": [
{ "key": "instructions", "label": "Instrucciones", "status": "error", "message": "Faltan las instrucciones del asistente." },
{ "key": "channels", "label": "Canales", "status": "warning", "message": "WhatsApp sin número asignado: no recibirá mensajes por ahí." },
{ "key": "model", "label": "Modelo de IA", "status": "ok" }
]
}
}

status es ok, info, warning o error. ready es true cuando ningún elemento está en error. Los elementos en ok no traen message.

Las sesiones son las conversaciones del Playground (chat de prueba del panel). Las ejecuciones de tools se leen de esas mismas sesiones — cada turno del chat guarda ahí las tools que el asistente llamó, no solo las de tipo Flow.

MétodoRutaDescripción
GET/agents/:id/sessionsListar sesiones de prueba
GET/agents/:id/sessions/:sessionIdObtener una sesión (mensajes completos)
DELETE/agents/:id/sessions/:sessionIdLimpiar una sesión
GET/agents/:id/tool-executionsHistorial de ejecuciones de tools (paginado por cursor)
GET/workspaces/:workspaceId/agents/:id/tool-executions
ParámetroTipoDescripción
limitnúmeroCantidad máxima de ejecuciones a devolver. Por defecto 50.
cursorstringId de la última sesión de la página anterior, para paginar hacia atrás.

Waiify conserva versiones de la configuración del asistente (instrucciones, comportamiento, herramientas, canales, conocimiento y widget). Sirven para comparar, etiquetar y volver atrás, total o por partes.

MétodoRutaDescripción
GET/agents/:id/prompt-versionsListar versiones (paginado)
POST/agents/:id/prompt-versionsGuardar la configuración actual como una versión con nombre
GET/agents/:id/prompt-versions/:versionIdObtener una versión (snapshot completo)
PATCH/agents/:id/prompt-versions/:versionId/tagEtiquetar (o quitar la etiqueta de) una versión
POST/agents/:id/prompt-versions/:versionId/rollbackRestaurar el asistente a esa versión (todo o por partes)
DELETE/agents/:id/prompt-versions/:versionIdEliminar una versión
POST/workspaces/:workspaceId/agents/:id/prompt-versions

Guarda la configuración actual del asistente como una versión; no hace falta enviar el contenido. Requiere assistants:edit.

CampoTipoRequeridoDescripción
labelstring (1-120)SíNombre de la versión (ej. “Antes de la campaña de julio”).
tagstring (máx. 40)NoEtiqueta corta, única dentro del asistente. Si ya existe, responde 409.
POST/workspaces/:workspaceId/agents/:id/prompt-versions/:versionId/rollback

Restaura el asistente a esa versión pasando por el guardado normal, con bloqueo optimista, y ajusta lo que ya no existe (un modelo retirado, un contexto, documentos o flujos eliminados). Antes de aplicar guarda una copia de respaldo de la configuración actual. No restaura la configuración de handoff ni las secuencias de seguimiento: son relaciones aparte y quedan como están.

Cuerpo opcional:

CampoTipoDescripción
partsarray de prompt | behavior | tools | channels | knowledge | widgetQué partes restaurar. Si se omite, se restaura todo.
expectedVersionenteroVersión del asistente que tenía cargada quien restaura; si alguien más lo editó, el servidor rechaza para no pisar sus cambios. Si se omite, usa la versión actual.
MétodoRutaDescripción
GET/knowledgeListar documentos, paginado (search, status, category y tag repetibles, usage=in_use|unused, ids, page, limit máx. 100). Cada documento incluye usedBy con los asistentes de chat y de voz que lo usan. search busca en título, categoría, nombre de archivo y etiquetas; searchContent=1 añade el contenido completo (lento con muchos documentos).
POST/knowledge/searchIgual que el listado, con los filtros en el cuerpo; útil con ids (hasta 3000), que no caben en la URL
GET/knowledge/facetsCategorías y etiquetas existentes con su conteo
GET/knowledge/statsEstadísticas (totalDocs, totalChunks, byStatus)
GET/knowledge/:idObtener documento (con contenido completo)
POST/knowledgeIndexar texto directo
POST/knowledge/uploadSubir archivo (.pdf .txt .docx .csv .xlsx .xls, máx. 10 MB)
PATCH/knowledge/:idEditar (reindexa si cambia content)
POST/knowledge/:id/retryReintentar un documento en estado ERROR
POST/knowledge/:id/similarity/dismissDescartar el aviso de “documento muy similar a otro”
POST/knowledge/:id/similarity/replaceEliminar el documento anterior similar y quedarte con este
DELETE/knowledge/:idEliminar documento

status es uno de PENDING, PROCESSING, READY, ERROR — el documento empieza en PENDING/PROCESSING y pasa a READY cuando termina de indexarse, o ERROR si falló (con el motivo en errorMsg). Para que un asistente lo use, agrégalo a su knowledgeDocIds con un PATCH a /agents/:id (se abre en una pestaña nueva). Ver gestión de la base de conocimiento (se abre en una pestaña nueva).

POST/workspaces/:workspaceId/knowledge
CampoTipoRequeridoDescripción
titlestring (1-300)SíTítulo del documento.
contentstring (1-500 000)SíContenido a indexar.
categorystring (máx. 100)NoCategoría libre.
tagsarray de string (máx. 20, 50 c/u)NoEtiquetas.
POST/workspaces/:workspaceId/knowledge/upload

Petición multipart/form-data: el campo del archivo se llama file. El backend extrae el texto del PDF/DOCX/CSV/XLSX/TXT y lo indexa igual que indexar texto (se abre en una pestaña nueva). Si no logra extraer texto (ej. un PDF escaneado sin OCR), responde 400.

CampoTipoRequeridoDescripción
filearchivoSí.pdf, .txt, .docx, .csv, .xlsx o .xls. Máx. 10 MB.
titlestringNoTítulo del documento. Por defecto, el nombre del archivo.
categorystringNoCategoría libre.
PATCH/workspaces/:workspaceId/knowledge/:id
CampoTipoRequeridoDescripción
titlestring (1-300)NoNuevo título.
contentstring (1-500 000)NoNuevo contenido — si cambia, se reindexa.
categorystring (máx. 100)NoNueva categoría.
tagsarray de stringNoNuevas etiquetas.
enabledbooleanNoActiva/desactiva el documento para la búsqueda de TODOS los asistentes que lo usan, sin borrar sus chunks ya indexados.

El único endpoint de chat pensado para integraciones externas es el del widget web (se abre en una pestaña nueva). No usa tu API key: se autentica con el widgetToken público del workspace (el mismo que va incrustado en el snippet que instalas en tu sitio — ver instalar el widget (se abre en una pestaña nueva)), pensado para vivir en HTML público. No requiere Authorization.

MétodoRutaDescripción
GET/widget/config?token=Datos públicos del workspace (nombre, logo, idioma)
GET/widget/appearance?token=&agentId=Apariencia en vivo del widget de un asistente
POST/widget/chatEnviar un mensaje al asistente
GET/widget/history?token=&conversationId=Historial de una conversación
POST/widget/closeMarcar la conversación como cerrada (al salir del sitio)
POST/widget/chat
CampoTipoRequeridoDescripción
tokenstringSíEl widgetToken público del workspace.
messagestringSíMensaje del visitante.
agentIdstringRecomendadoAsistente que debe responder (debe tener el canal Web widget activo). Si se omite (instalaciones antiguas), responde el asistente activo más antiguo con ese canal; si no hay ninguno, la petición se rechaza.
conversationIdstringNoPara continuar una conversación existente; se omite en el primer mensaje.
visitorIdstringNoIdentificador del visitante, para reconocerlo en mensajes futuros.
visitorName / visitorEmailstringNoDatos del visitante, si ya los tienes.