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).
Asistentes de chat
Sección titulada «Asistentes de chat»| Método | Ruta | Descripción |
|---|---|---|
GET | /agents | Listar asistentes |
POST | /agents | Crear asistente |
GET | /agents/:id | Obtener asistente |
PATCH | /agents/:id | Actualizar |
GET | /agents/:id/preflight | Revisión antes de activar |
DELETE | /agents/:id | Eliminar |
POST | /agents/:id/duplicate | Duplicar (copia toda la configuración, incluido handoff y follow-ups) |
POST | /agents/:id/widget-logo | Subir logo del widget (multipart/form-data, campo logo, imagen, máx. 2 MB) |
POST | /agents/:id/website/import | Rastrear una URL y usarla como documento de conocimiento del asistente |
Sesiones del Playground
Sección titulada «Sesiones del Playground»Cuelgan de /agents/:id/playground y requieren el permiso assistants:view. Ver Playground (se abre en una pestaña nueva).
| Método | Ruta | Descripción |
|---|---|---|
POST | /agents/:id/playground/sessions | Crear una sesión: contacto y conversación de prueba. Limpia las sesiones anteriores del usuario en ese asistente |
GET | /agents/:id/playground/sessions/:sessionId | Estado de la conversación (ai, queued, with_advisor, resolved, transferred) y datos del cliente simulado |
POST | /agents/:id/playground/sessions/:sessionId/resume | Reiniciar el estado para que el asistente vuelva a responder |
DELETE | /agents/:id/playground/sessions/:sessionId | Descartar 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.
Crear asistente — cuerpo de la petición
Sección titulada «Crear asistente — cuerpo de la petición»| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
name | string (2-60) | Sí | Nombre del asistente. |
systemPrompt | string (10-20 000) | Sí | Instrucciones del asistente. |
description | string (máx. 2000) | No | Descripción interna. |
avatarUrl | string | No | URL del avatar. |
welcomeMessage | string (máx. 1000) | No | Mensaje de saludo inicial. |
model | string | No | Modelo 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. |
language | es | en | multi | No | Idioma del asistente (se abre en una pestaña nueva): español, inglés o bilingüe. Por defecto es. |
temperature | número (0-2) | No | Creatividad de las respuestas. Por defecto 0.7. |
maxTokens | entero (1-8000) | No | Tope de tokens de la respuesta. Por defecto 600. |
autoCaptureLeadInfo | boolean | No | Captura automática de datos del contacto. Por defecto true. |
channels | array de WHATSAPP | WEB_WIDGET | No | Canales donde responde. Por defecto ["WEB_WIDGET"]. |
tools | array (máx. 50) | No | Herramientas del asistente — ver herramientas de asistentes (se abre en una pestaña nueva). |
knowledgeDocIds | array de string (máx. 200) | No | Documentos de conocimiento (se abre en una pestaña nueva) vinculados. |
contextId | string | No | ID de un contexto de empresa (se abre en una pestaña nueva) existente en el workspace. |
widgetColor / widgetBgColor | string (hex) | No | Colores del widget. Por defecto #2563eb / #0d1424. |
widgetPosition | left | right | No | Posición del widget. Por defecto right. |
widgetBotName / widgetGreeting / widgetLogoUrl | string | No | Personalización del widget. |
/workspaces/:workspaceId/agentsActualizar asistente
Sección titulada «Actualizar asistente»/workspaces/:workspaceId/agents/:idAcepta los mismos campos que crear (se abre en una pestaña nueva), todos opcionales — es un merge parcial. Además admite:
| Campo | Tipo | Descripción |
|---|---|---|
isActive | boolean | Activa 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. |
expectedVersion | entero | Bloqueo 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. |
versionLabel | string (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ó. |
Duplicar asistente
Sección titulada «Duplicar asistente»/workspaces/:workspaceId/agents/:id/duplicateCrea 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)”.
Revisión antes de activar
Sección titulada «Revisión antes de activar»/workspaces/:workspaceId/agents/:id/preflightDevuelve 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.
{ "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.
Sesiones y ejecuciones de tools
Sección titulada «Sesiones y ejecuciones de tools»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étodo | Ruta | Descripción |
|---|---|---|
GET | /agents/:id/sessions | Listar sesiones de prueba |
GET | /agents/:id/sessions/:sessionId | Obtener una sesión (mensajes completos) |
DELETE | /agents/:id/sessions/:sessionId | Limpiar una sesión |
GET | /agents/:id/tool-executions | Historial de ejecuciones de tools (paginado por cursor) |
Listar ejecuciones de tools
Sección titulada «Listar ejecuciones de tools»/workspaces/:workspaceId/agents/:id/tool-executionsParámetros de query
Sección titulada «Parámetros de query»| Parámetro | Tipo | Descripción |
|---|---|---|
limit | número | Cantidad máxima de ejecuciones a devolver. Por defecto 50. |
cursor | string | Id de la última sesión de la página anterior, para paginar hacia atrás. |
Versiones de prompt
Sección titulada «Versiones de prompt»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étodo | Ruta | Descripción |
|---|---|---|
GET | /agents/:id/prompt-versions | Listar versiones (paginado) |
POST | /agents/:id/prompt-versions | Guardar la configuración actual como una versión con nombre |
GET | /agents/:id/prompt-versions/:versionId | Obtener una versión (snapshot completo) |
PATCH | /agents/:id/prompt-versions/:versionId/tag | Etiquetar (o quitar la etiqueta de) una versión |
POST | /agents/:id/prompt-versions/:versionId/rollback | Restaurar el asistente a esa versión (todo o por partes) |
DELETE | /agents/:id/prompt-versions/:versionId | Eliminar una versión |
Guardar versión
Sección titulada «Guardar versión»/workspaces/:workspaceId/agents/:id/prompt-versionsGuarda la configuración actual del asistente como una versión; no hace falta enviar el contenido. Requiere assistants:edit.
Cuerpo de la petición
Sección titulada «Cuerpo de la petición»| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
label | string (1-120) | Sí | Nombre de la versión (ej. “Antes de la campaña de julio”). |
tag | string (máx. 40) | No | Etiqueta corta, única dentro del asistente. Si ya existe, responde 409. |
Rollback
Sección titulada «Rollback»/workspaces/:workspaceId/agents/:id/prompt-versions/:versionId/rollbackRestaura 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:
| Campo | Tipo | Descripción |
|---|---|---|
parts | array de prompt | behavior | tools | channels | knowledge | widget | Qué partes restaurar. Si se omite, se restaura todo. |
expectedVersion | entero | Versió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. |
Base de conocimiento
Sección titulada «Base de conocimiento»| Método | Ruta | Descripción |
|---|---|---|
GET | /knowledge | Listar 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/search | Igual que el listado, con los filtros en el cuerpo; útil con ids (hasta 3000), que no caben en la URL |
GET | /knowledge/facets | Categorías y etiquetas existentes con su conteo |
GET | /knowledge/stats | Estadísticas (totalDocs, totalChunks, byStatus) |
GET | /knowledge/:id | Obtener documento (con contenido completo) |
POST | /knowledge | Indexar texto directo |
POST | /knowledge/upload | Subir archivo (.pdf .txt .docx .csv .xlsx .xls, máx. 10 MB) |
PATCH | /knowledge/:id | Editar (reindexa si cambia content) |
POST | /knowledge/:id/retry | Reintentar un documento en estado ERROR |
POST | /knowledge/:id/similarity/dismiss | Descartar el aviso de “documento muy similar a otro” |
POST | /knowledge/:id/similarity/replace | Eliminar el documento anterior similar y quedarte con este |
DELETE | /knowledge/:id | Eliminar 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).
Indexar texto
Sección titulada «Indexar texto»/workspaces/:workspaceId/knowledgeCuerpo de la petición
Sección titulada «Cuerpo de la petición»| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
title | string (1-300) | Sí | Título del documento. |
content | string (1-500 000) | Sí | Contenido a indexar. |
category | string (máx. 100) | No | Categoría libre. |
tags | array de string (máx. 20, 50 c/u) | No | Etiquetas. |
Subir archivo
Sección titulada «Subir archivo»/workspaces/:workspaceId/knowledge/uploadPetició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.
Campos del formulario
Sección titulada «Campos del formulario»| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
file | archivo | Sí | .pdf, .txt, .docx, .csv, .xlsx o .xls. Máx. 10 MB. |
title | string | No | Título del documento. Por defecto, el nombre del archivo. |
category | string | No | Categoría libre. |
Actualizar documento
Sección titulada «Actualizar documento»/workspaces/:workspaceId/knowledge/:idCuerpo de la petición
Sección titulada «Cuerpo de la petición»| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
title | string (1-300) | No | Nuevo título. |
content | string (1-500 000) | No | Nuevo contenido — si cambia, se reindexa. |
category | string (máx. 100) | No | Nueva categoría. |
tags | array de string | No | Nuevas etiquetas. |
enabled | boolean | No | Activa/desactiva el documento para la búsqueda de TODOS los asistentes que lo usan, sin borrar sus chunks ya indexados. |
Chat público (widget)
Sección titulada «Chat público (widget)»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étodo | Ruta | Descripció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/chat | Enviar un mensaje al asistente |
GET | /widget/history?token=&conversationId= | Historial de una conversación |
POST | /widget/close | Marcar la conversación como cerrada (al salir del sitio) |
/widget/chatCuerpo de la petición
Sección titulada «Cuerpo de la petición»| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
token | string | Sí | El widgetToken público del workspace. |
message | string | Sí | Mensaje del visitante. |
agentId | string | Recomendado | Asistente 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. |
conversationId | string | No | Para continuar una conversación existente; se omite en el primer mensaje. |
visitorId | string | No | Identificador del visitante, para reconocerlo en mensajes futuros. |
visitorName / visitorEmail | string | No | Datos del visitante, si ya los tienes. |
Relacionado
Sección titulada «Relacionado»- Introducción a asistentes (se abre en una pestaña nueva) · Base de conocimiento (se abre en una pestaña nueva) · Widget web (se abre en una pestaña nueva)
- Conversaciones y mensajes (se abre en una pestaña nueva) — gestionar desde el inbox lo que llega por el widget o WhatsApp.
