Asistentes y base de conocimiento

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

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
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

Nota

POST /agents/:id/chat y /agents/:id/chat/stream también existen, pero son el chat de prueba del panel (Playground). GET /agents/:id/sessions lista esas conversaciones de prueba. Para chatear con un asistente desde fuera de Waiify usa el widget público más abajo.

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	gemini-2.5-flash | gpt-4o	No	Modelo de IA. Por defecto gemini-2.5-flash.
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.
knowledgeDocIds	array de string (máx. 200)	No	Documentos de conocimiento vinculados.
contextId	string	No	ID de un contexto de empresa 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.

POST /workspaces/:workspaceId/agents Copiar

cURL

curl -X POST "https://api.waiify.com/workspaces/WORKSPACE_ID/agents" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Asistente de ventas",
    "systemPrompt": "Eres el asistente de ventas de Acme. Responde en español, de forma breve y cordial.",
    "model": "gemini-2.5-flash",
    "channels": ["WEB_WIDGET"]
  }'

Node

const res = await fetch('https://api.waiify.com/workspaces/WORKSPACE_ID/agents', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer TU_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Asistente de ventas',
    systemPrompt: 'Eres el asistente de ventas de Acme. Responde en español, de forma breve y cordial.',
    model: 'gemini-2.5-flash',
    channels: ['WEB_WIDGET'],
  }),
});
const { data: agent } = await res.json();

Python

import requests

res = requests.post(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/agents",
    headers={"Authorization": "Bearer TU_API_KEY"},
    json={
        "name": "Asistente de ventas",
        "systemPrompt": "Eres el asistente de ventas de Acme. Responde en español, de forma breve y cordial.",
        "model": "gemini-2.5-flash",
        "channels": ["WEB_WIDGET"],
    },
)
agent = res.json()["data"]

Respuesta 201

{
  "success": true,
  "data": {
    "id": "agent_abc123",
    "name": "Asistente de ventas",
    "model": "gemini-2.5-flash",
    "channels": ["WEB_WIDGET"],
    "isActive": true,
    "version": 1,
    "createdAt": "2026-06-18T09:00:00.000Z"
  }
}

Actualizar asistente

PATCH /workspaces/:workspaceId/agents/:id Copiar

Acepta los mismos campos que crear, todos opcionales — es un merge parcial. Además admite:

Campo	Tipo	Descripción
isActive	boolean	Activa o desactiva el asistente.
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 que se autoguarda si systemPrompt cambió.

cURL

curl -X PATCH "https://api.waiify.com/workspaces/WORKSPACE_ID/agents/AGENT_ID" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "isActive": false }'

Node

await fetch('https://api.waiify.com/workspaces/WORKSPACE_ID/agents/AGENT_ID', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer TU_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ isActive: false }),
});

Python

import requests

requests.patch(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/agents/AGENT_ID",
    headers={"Authorization": "Bearer TU_API_KEY"},
    json={"isActive": False},
)

Respuesta 200

{
  "success": true,
  "data": {
    "id": "agent_abc123",
    "name": "Asistente de ventas",
    "isActive": false,
    "updatedAt": "2026-06-18T10:00:00.000Z"
  }
}

Duplicar asistente

POST /workspaces/:workspaceId/agents/:id/duplicate Copiar

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)”.

Nota

Hay un límite de asistentes por workspace según el plan — duplicate lo verifica igual que create y devuelve 403 si ya lo alcanzaste.

cURL

curl -X POST "https://api.waiify.com/workspaces/WORKSPACE_ID/agents/AGENT_ID/duplicate" \
  -H "Authorization: Bearer TU_API_KEY"

Node

const res = await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/agents/AGENT_ID/duplicate',
  { method: 'POST', headers: { Authorization: 'Bearer TU_API_KEY' } }
);
const { data: copy } = await res.json();

Python

import requests

res = requests.post(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/agents/AGENT_ID/duplicate",
    headers={"Authorization": "Bearer TU_API_KEY"},
)
copy = res.json()["data"]

Respuesta 201

{
  "success": true,
  "data": {
    "id": "agent_def456",
    "name": "Asistente de ventas (copia)",
    "isActive": false,
    "createdAt": "2026-06-18T10:05:00.000Z"
  }
}

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

GET /workspaces/:workspaceId/agents/:id/tool-executions Copiar

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.

cURL

curl "https://api.waiify.com/workspaces/WORKSPACE_ID/agents/AGENT_ID/tool-executions?limit=20" \
  -H "Authorization: Bearer TU_API_KEY"

Node

const res = await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/agents/AGENT_ID/tool-executions?limit=20',
  { headers: { Authorization: 'Bearer TU_API_KEY' } }
);
const { data } = await res.json();

Python

import requests

res = requests.get(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/agents/AGENT_ID/tool-executions",
    headers={"Authorization": "Bearer TU_API_KEY"},
    params={"limit": 20},
)
data = res.json()["data"]

Respuesta 200

{
  "success": true,
  "data": {
    "entries": [
      {
        "toolCallId": "call_ab12",
        "toolName": "check_availability",
        "args": { "date": "2026-06-20" },
        "result": { "slots": ["10:00", "11:00"] },
        "flowId": "",
        "durationMs": 340,
        "sessionId": "sess_ab12cd34ef",
        "ts": "2026-06-18T09:30:00.000Z"
      }
    ],
    "nextCursor": null,
    "hasMore": false
  }
}

Versiones de prompt

Cada vez que se guarda un cambio en systemPrompt, model, temperature o maxTokens se puede conservar como una versión con historial. Sirve para comparar, etiquetar y volver atrás.

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 nueva
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
DELETE	/agents/:id/prompt-versions/:versionId	Eliminar una versión

Consejo

Solo se guardan automáticamente hasta 50 versiones sin etiqueta por asistente (FIFO: la más vieja se borra al llegar al tope). Las versiones con tag nunca se cuentan ni se borran solas.

Guardar versión

POST /workspaces/:workspaceId/agents/:id/prompt-versions Copiar

Cuerpo de la petición

Campo	Tipo	Requerido	Descripción
systemPrompt	string	Sí	Instrucciones a guardar en esta versión.
model	string	Sí	Modelo de esta versión.
temperature	número	Sí	Temperatura de esta versión.
maxTokens	número	Sí	Tope de tokens de esta versión.
label	string	No	Etiqueta legible (ej. “Antes de la campaña de julio”).
tag	string	No	Tag corto para identificarla en el selector.
promptSections / welcomeMessage	any / string	No	Se guardan en el snapshot si aplican.

cURL

curl -X POST "https://api.waiify.com/workspaces/WORKSPACE_ID/agents/AGENT_ID/prompt-versions" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "Eres el asistente de ventas de Acme...",
    "model": "gemini-2.5-flash",
    "temperature": 0.7,
    "maxTokens": 600,
    "label": "Antes de la campaña de julio"
  }'

Node

const res = await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/agents/AGENT_ID/prompt-versions',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer TU_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      systemPrompt: 'Eres el asistente de ventas de Acme...',
      model: 'gemini-2.5-flash',
      temperature: 0.7,
      maxTokens: 600,
      label: 'Antes de la campaña de julio',
    }),
  }
);
const { data: version } = await res.json();

Python

import requests

res = requests.post(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/agents/AGENT_ID/prompt-versions",
    headers={"Authorization": "Bearer TU_API_KEY"},
    json={
        "systemPrompt": "Eres el asistente de ventas de Acme...",
        "model": "gemini-2.5-flash",
        "temperature": 0.7,
        "maxTokens": 600,
        "label": "Antes de la campaña de julio",
    },
)
version = res.json()["data"]

Respuesta 201

{
  "success": true,
  "data": {
    "id": "pv_ab12cd34ef",
    "agentId": "agent_abc123",
    "label": "Antes de la campaña de julio",
    "tag": null,
    "createdAt": "2026-06-18T09:00:00.000Z"
  }
}

Rollback

POST /workspaces/:workspaceId/agents/:id/prompt-versions/:versionId/rollback Copiar

Restaura los campos escalares del asistente (nombre, prompt, modelo, temperatura, tools, canales, personalización del widget, etc.) al snapshot de esa versión. No restaura la configuración de handoff ni las secuencias de follow-up — esas son relaciones aparte y quedan como están, para no arriesgar jobs de seguimiento ya programados.

cURL

curl -X POST "https://api.waiify.com/workspaces/WORKSPACE_ID/agents/AGENT_ID/prompt-versions/VERSION_ID/rollback" \
  -H "Authorization: Bearer TU_API_KEY"

Node

const res = await fetch(
  'https://api.waiify.com/workspaces/WORKSPACE_ID/agents/AGENT_ID/prompt-versions/VERSION_ID/rollback',
  { method: 'POST', headers: { Authorization: 'Bearer TU_API_KEY' } }
);
const { data } = await res.json();

Python

import requests

res = requests.post(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/agents/AGENT_ID/prompt-versions/VERSION_ID/rollback",
    headers={"Authorization": "Bearer TU_API_KEY"},
)
data = res.json()["data"]

Respuesta 200

{
  "success": true,
  "message": "Rollback aplicado exitosamente",
  "data": {
    "id": "agent_abc123",
    "systemPrompt": "Eres el asistente de ventas de Acme...",
    "model": "gemini-2.5-flash",
    "updatedAt": "2026-06-18T10:15:00.000Z"
  }
}

Base de conocimiento

Método	Ruta	Descripción
GET	/knowledge	Listar documentos (search, status, category, page, limit)
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. Ver gestión de la base de conocimiento.

Indexar texto

POST /workspaces/:workspaceId/knowledge Copiar

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.

cURL

curl -X POST "https://api.waiify.com/workspaces/WORKSPACE_ID/knowledge" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Horario de atención", "content": "Atendemos de lunes a viernes de 9 a 18 h." }'

Node

const res = await fetch('https://api.waiify.com/workspaces/WORKSPACE_ID/knowledge', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer TU_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Horario de atención',
    content: 'Atendemos de lunes a viernes de 9 a 18 h.',
  }),
});
const { data: doc } = await res.json();

Python

import requests

res = requests.post(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/knowledge",
    headers={"Authorization": "Bearer TU_API_KEY"},
    json={"title": "Horario de atención", "content": "Atendemos de lunes a viernes de 9 a 18 h."},
)
doc = res.json()["data"]

Respuesta 201

{
  "success": true,
  "data": {
    "id": "doc_abc123",
    "title": "Horario de atención",
    "status": "PENDING",
    "chunkCount": 0,
    "createdAt": "2026-06-18T09:00:00.000Z"
  }
}

Subir archivo

POST /workspaces/:workspaceId/knowledge/upload Copiar

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. Si no logra extraer texto (ej. un PDF escaneado sin OCR), responde 400.

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.

cURL

curl -X POST "https://api.waiify.com/workspaces/WORKSPACE_ID/knowledge/upload" \
  -H "Authorization: Bearer TU_API_KEY" \
  -F "file=@catalogo.pdf" \
  -F "title=Catálogo de productos"

Node

import { readFile } from 'node:fs/promises';

const form = new FormData();
form.append('file', new Blob([await readFile('catalogo.pdf')]), 'catalogo.pdf');
form.append('title', 'Catálogo de productos');

const res = await fetch('https://api.waiify.com/workspaces/WORKSPACE_ID/knowledge/upload', {
  method: 'POST',
  headers: { Authorization: 'Bearer TU_API_KEY' },
  body: form,
});
const { data: doc } = await res.json();

Python

import requests

with open("catalogo.pdf", "rb") as f:
    res = requests.post(
        "https://api.waiify.com/workspaces/WORKSPACE_ID/knowledge/upload",
        headers={"Authorization": "Bearer TU_API_KEY"},
        files={"file": ("catalogo.pdf", f)},
        data={"title": "Catálogo de productos"},
    )
doc = res.json()["data"]

Respuesta 201

{
  "success": true,
  "message": "Documento subido. Los embeddings se están procesando en segundo plano.",
  "data": {
    "id": "doc_bcd234",
    "title": "Catálogo de productos",
    "status": "PENDING",
    "fileSize": 245678,
    "createdAt": "2026-06-18T09:00:00.000Z"
  }
}

Actualizar documento

PATCH /workspaces/:workspaceId/knowledge/:id Copiar

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.

cURL

curl -X PATCH "https://api.waiify.com/workspaces/WORKSPACE_ID/knowledge/DOC_ID" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Node

await fetch('https://api.waiify.com/workspaces/WORKSPACE_ID/knowledge/DOC_ID', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer TU_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ enabled: false }),
});

Python

import requests

requests.patch(
    "https://api.waiify.com/workspaces/WORKSPACE_ID/knowledge/DOC_ID",
    headers={"Authorization": "Bearer TU_API_KEY"},
    json={"enabled": False},
)

Respuesta 200

{
  "success": true,
  "message": "Documento actualizado",
  "data": {
    "id": "doc_abc123",
    "title": "Horario de atención",
    "enabled": false,
    "status": "READY"
  }
}

Chat público (widget)

El único endpoint de chat pensado para integraciones externas es el del widget web. 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), 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)

POST /widget/chat Copiar

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	No	Asistente que debe responder (debe tener el canal Web widget activo).
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.

cURL

curl -X POST "https://api.waiify.com/widget/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "TU_WIDGET_TOKEN",
    "agentId": "AGENT_ID",
    "message": "¿Cuál es el horario de atención?",
    "visitorId": "visitor-123"
  }'

Node

const res = await fetch('https://api.waiify.com/widget/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    token: 'TU_WIDGET_TOKEN',
    agentId: 'AGENT_ID',
    message: '¿Cuál es el horario de atención?',
    visitorId: 'visitor-123',
  }),
});
const { data } = await res.json();

Python

import requests

res = requests.post(
    "https://api.waiify.com/widget/chat",
    json={
        "token": "TU_WIDGET_TOKEN",
        "agentId": "AGENT_ID",
        "message": "¿Cuál es el horario de atención?",
        "visitorId": "visitor-123",
    },
)
data = res.json()["data"]

Respuesta 200

{
  "success": true,
  "data": {
    "conversationId": "conv_abc123",
    "message": {
      "id": "msg_abc123",
      "content": "Atendemos de lunes a viernes de 9 a 18 h.",
      "role": "BOT",
      "sentAt": "2026-06-18T09:00:00.000Z"
    }
  }
}

Guarda el conversationId de la respuesta y envíalo en los mensajes siguientes para continuar el mismo hilo. Si un miembro de tu equipo toma el control de esa conversación, la respuesta viene con "message": null y "humanControlled": true — el bot no responde mientras un humano atiende.

Relacionado

• Introducción a asistentes · Base de conocimiento · Widget web
• Conversaciones y mensajes — gestionar desde el inbox lo que llega por el widget o WhatsApp.