https://api.zelto.ai/mcp. Cualquier cliente compatible con MCP puede conectarse y obtener acceso de lectura a sus agentes, conversaciones, transcripciones, reseñas y hallazgos, además de un pequeño conjunto de herramientas de escritura para el flujo de trabajo de revisión basado en bucket.
La mayoría de las herramientas de lectura y escritura reflejan un público API REST
Sin embargo, algunas herramientas van más allá de la superficie REST: colas de revisión, cambios, población de cubos, conexión/importación de proveedores de voz y configuración de la organización son exclusivas de MCP. El Espejos En cada columna de la tabla siguiente se indica cuál es cuál (— (MCP-only) significa que no hay equivalente de RESTO).
¿Nuevo aquí? A bordo con un agente impulsa toda la configuración: conecta un proveedor, recibe conversaciones, crea un monitor y enruta hallazgos herramientas de onboarding abajo.
¿Estás armando un benchmark? Crear casos con la API describe las herramientas de casos de benchmark (add_benchmark_cases,add_benchmark_cases_from_conversations,add_benchmark_cases_from_traces).
Integración con TypeScript
El paquete oficial de npm para proyectos TypeScript eszelto-sdk.
El envío de conversaciones requiere la versión 0.4.0 o posterior. Antes de instalar,
consulta npm view zelto-sdk version: si 0.4.0 todavía no está publicada, usa la
integración HTTP de esta guía. La versión 0.3.0 solo ofrece la API anterior de
analítica web. Cuando esté disponible, ejecuta npm install zelto-sdk@^0.4.0 y usa
Zelto.sendConversation en el servidor; consulta el ejemplo TypeScript de la guía
de envío. Guarda la clave en variables de entorno exclusivas del servidor.
MCP se conecta de forma remota sin paquete npm. «Install Zelto in this project»
es una instrucción para el agente de programación, no un comando de terminal.
Crear tu cuenta usando solo MCP
El endpoint públicohttps://api.zelto.ai/mcp/signup expone start_signup con
{}. Devuelve signInUrl, signupUrl y mcpUrl. El agente te entrega el enlace
para iniciar sesión o registrarte; vos elegís tus credenciales y verificás el
correo con Verificar mi cuenta. El agente nunca genera una contraseña ni
te pide el código del email.
Conectá el cliente al mcpUrl devuelto usando su flujo OAuth habitual y autorizá
el acceso a la organización en el navegador. El cliente gestiona PKCE y state.
Sirve para cuentas nuevas y existentes. Si el cliente no admite OAuth, configurá
una clave API directamente en su gestor de secretos local, nunca en el chat.
El endpoint de registro no accede a datos ni genera claves.
Si abrís el enlace en otro navegador o para otra cuenta, Zelto muestra el correo
y te pide confirmar antes de iniciar sesión.
Obtener una clave de API
Acuña uno enhttps://dashboard.zelto.ai/org/<your-slug>/settings/integrations →
Carga de conversaciones API. La clave se muestra una vez copiarlo inmediatamente. La misma clave funciona para el API REST Acuñar y revocar claves es una acción de propietario/administrador; si tiene la member
de un rol, pregunte a un propietario o administrador por uno (y vea
Tu papel decide lo que puedes hacer).
Exportarlo para los fragmentos a continuación:
https://api.zelto.ai/v1.
Iniciar sesión con OAuth
Clientes que apoyan MCP remoto OAuth Claude, Cursor, VS Code y otros pueden conectarse sin acuñar una clave. Apunte al cliente a la URL del servidor e inicie sesión a través de su navegador:¿Usa Claude en la web o la aplicación Claude Desktop? Conectar Zelto a Claude explica cómo agregarlo como conector personalizado.
Clientes
Código Claude
Añadir el servidor a~/.claude.json (Crear el archivo si no existe):
/mcp (Elemento). zelto: herramientas aparecen en el selector; zelto:health devuelve su id de la organización como prueba de humo.
La página de Integraciones también muestra este fragmento pre-llenado con el host actual ir a Configuración → Integraciones → AI agente access y abrir el Claude tarjeta.
OpenAI Codex CLI
Codex CLI soporta servidores MCP a través de~/.codex/config.toml. Añadir una entrada de servidor bajo [mcp_servers.zelto]:
codex y le pregunta algo que necesite sus datos, p. ej.
“Enumera mis últimas 20 conversaciones y fracasos de grupo por agente”. El Codex descubre el zelto: herramientas automáticamente.
Cursor
~/.cursor/mcp.json acepta la misma forma que Claude Code:
zelto Las herramientas aparecen en la barra lateral del chat.
Continuar, Zed y otros clientes Streamable-HTTP
El servidor habla HTTP Streamable, por lo que cualquier cliente que acepte una URL +Authorization header funciona. Continuar usos config.yaml:
~/.config/zed/settings.json bajo context_servers.zelto
con el mismo url + headers forma.
Prueba rápida de humo (curl)
Si un cliente se comporta mal, verifique su clave y conectividad con la API REST: la misma clave autentica ambos:
200 con un { "data": [...] } página significa que el servidor y su clave son buenos el problema está en la configuración del cliente. Desde dentro de un cliente conectado, el health herramienta devuelve { "status": "ok", "orgId": "…" } como el mismo cheque.
A 401 significa que la credencial es el problema: la clave se eliminó o la persona a la que pertenece perdió el acceso a la organización (se eliminó o se prohibió su cuenta). Acuñar una clave nueva solo ayuda si su propia cuenta aún tiene acceso a esa organización.
Autenticación
Cada petición lleva unAuthorization: Bearer <token> donde se encuentra el token o bien un Clave API o un token de acceso OAuth obtenido por firmando. Solicitudes sin token o con devolución de token caducada/no válida 401 De cualquier manera, el token se resuelve en un solo servidor de la organización: una clave de API de su organización integrada, un token OAuth de la organización que eligió al dar su consentimiento, y una herramienta solo ve los datos de esa organización.
Tu papel decide lo que puedes hacer
La autenticación prueba que organización sobre la que se puede actuar, no ¿Qué Las herramientas que administran la propia organización requieren el uso de laowner o
admin función la misma puerta se aplica al salpicadero:
update_org_settings · invite_member · remove_member ·
save_usage_report_config · set_voice_tool_access · delete_agent ·
set_findings_delivery · merge_findings · delete_finding ·
approve_finding_candidate · reject_finding_candidate · update_finding
(Sólo cuando pases title los campos de clasificación permanecen abiertos a cualquier miembro)
update_member_role es más estricto aún: Propietario solamente, y se niega a cambiar su propio papel. remove_member También se niega a eliminar su propia membresía, sea cual sea su función, pregunte a otro propietario o administrador.
Un token perteneciente a member alcanza cada herramienta de lectura y cada escritura no administrativa, pero las herramientas anteriores regresan
Only an organization owner or admin can perform this action. En lugar de actuar (update_member_role devoluciones Only an organization owner can perform this action.). Esto es cierto para ambos tipos de credenciales: una clave o token actúa como la persona detrás de ella, y esta puerta lee el papel de esa persona en el momento de la llamada en lugar de en el momento de la publicación. Para sacar una credencial del servicio por completo, revoquela: vea
Claves de API. Quitar a esa persona de la organización (o prohibir su cuenta) hace lo mismo implícitamente: cada solicitud vuelve a verificar al propietario, por lo que sus claves y tokens OAuth dejan de funcionar en la próxima llamada.
Alcance de lectura y escritura
Un cliente OAuth pide un alcance de acceso al dar el consentimiento, y el servidor lo aplica antes de que se ejecute la herramienta:write— todas las herramientas, incluidas las que modifican datos. Implicaread.read— solo las herramientas de lectura. Un token con alcancereadque llama a una herramienta de escritura recibe un error de herramienta en lugar de un resultado:This credential is read-only and cannot call "<tool>". Reconnect with the "write" scope to allow changes.La llamada nunca llega a la herramienta, y el intento queda registrado en la actividad MCP de la organización. La única excepción essend_feedback, que cualquier credencial puede usar (consulta Feedback de agentes).- Sin alcance de acceso — los tokens emitidos antes de que existieran los alcances conservan acceso completo.
POST /mcp. Un lote (array) JSON-RPC que
contenga una invocación de herramienta se rechaza con 400; los cuerpos de
solicitud de más de 4 MiB se rechazan con 413.
Herramientas
Leer herramientas
read_docs es solo MCP llámelo sin argumentos para listar cada página de documentación (slug + título + descripción), luego pase un path (p. ej.
findings o integrations/slack) para leer la página completa de Markdown.
Los argumentos de las herramientas nombran el id de una entidad de dos maneras según la herramienta: un hallazgo es id en get_finding / update_finding pero findingId en approve_finding_candidate; un monitor es monitorId en get_monitor pero id en update_monitor, y así sucesivamente. Las tablas muestran el nombre canónico. El servidor también acepta la otra forma (id o <entidad>Id) para los ids de hallazgos, monitores, conversaciones, agentes, cambios, buckets y colas, de modo que una llamada con el nombre equivocado sigue funcionando. Un argumento canónico explícito siempre tiene prioridad.
status enums: opiniones aceptar pending / reviewed / flagged; hallazgos aceptar open / acknowledged / resolved / ignored. hallazgo priority
acepta none / low / medium / high / urgent.
Vistas interactivas (MCP Apps)
Siete herramientas abren la experiencia de hallazgos y monitores de Zelto dentro de la conversación en lugar de devolver texto. Los clientes que admiten MCP Apps las muestran en línea; los demás reciben un resultado vacío, así que use allí la herramientabrowse_* o list_* equivalente.
Son una sola vista conectada, así que puede seguir enlaces en ambos sentidos: de la
lista a un hallazgo, de un hallazgo (o de un ejemplo de conversación en su texto) a la
transcripción de una conversación, de una transcripción al trace de la misma conversación y de
vuelta, y de una conversación a los hallazgos a los que pertenece. Desde los resultados de
un monitor puede abrir la transcripción de una conversación y volver al monitor donde lo dejó.
Lista de hallazgos. Lo que muestra la página de Hallazgos: pestañas de estado con
contadores, búsqueda, filtros por prioridad, responsable y agente, columnas ordenables
(última vez visto, antigüedad, conversaciones, volumen, prioridad) y un responsable en cada
fila. Los argumentos eligen cómo se abre — por ejemplo
{ "status": "open", "priority": ["urgent", "high"], "assignee": "me" } — y después
puede cambiar cualquier filtro. assignee acepta el UUID de un usuario, me o
unassigned.
Hallazgo. El contenido de texto enriquecido del hallazgo (incluidos los fragmentos
de prompt del agente y los ejemplos de conversación), sus estadísticas y sus conversaciones
vinculadas.
Tarjeta de transcripción. Cada turno con su interlocutor y su hora, una búsqueda
que resalta las coincidencias, y las llamadas a herramientas con sus argumentos,
resultados y errores. Abierta desde un hallazgo (o con findingId), muestra además las
anotaciones de ese hallazgo, ubicadas en el momento de la conversación al que se refieren.
Tarjeta de trace. Todo lo que la página de Traces permite hacer con un trace:
- Tres vistas de los spans — Árbol, Línea de tiempo (una cascada que puede ampliar
de 1× a 8× y ajustar) y Pistas (un carril por tipo de span) — con una selección
compartida y búsqueda de spans por nombre, tipo o modelo. El argumento
viewdeshow_traceelige con cuál se abre. - Resumen — tiempo por paso (promedio, con mínimo, máximo, suma, cantidad y costo a pedido), tiempo de respuesta por turno (expandible a los spans de cada turno), atributos por span y las líneas de log del trace.
- Detalle del span — tipo, hora, duración, modelo, tokens, costo y cualquier mensaje de error, con la entrada y salida del span (formateadas por rol o sin procesar), sus atributos y logs, y anterior / siguiente para recorrer el trace en orden de tiempo.
{ "status": "paused" }, y después puede cambiar
cualquier filtro.
Monitor. Cuatro pestañas, como la página del monitor:
- Resumen — conteos de evaluadas y afectadas, la tendencia de la tasa de afectación (o el puntaje promedio) en 7, 30 o 90 días, un gráfico por cada etapa que produce un sí/no, una categoría o un número, y un embudo de pasos completados por cada verificación de flujo.
- Resultados — una fila por conversación evaluada con el veredicto en las palabras del propio monitor, el agente y el razonamiento del modelo en cada etapa. Filtre todos, afectados o no afectados, y recorra las páginas. Un resultado que falló al evaluarse, o que no se pudo puntuar, se muestra como tal, nunca como “no afectado”. Abra un resultado para leer la transcripción de la conversación.
- Configuración — dónde aplica, qué decide el veredicto, las etiquetas de resultado,
el muestreo, el modelo, la versión y cada etapa del pipeline con su instrucción. Es de
solo lectura: para cambiar un monitor, pídaselo a Claude (puede usar
update_monitor) o use la app de Zelto. - Alertas — la regla de umbral y a quién se notifica, de solo lectura; use
save_monitor_alertpara cambiarla.
tab y resultsFilter de show_monitor eligen con qué se abre.
Edición. La prioridad, el estado y el responsable se editan en la lista y en un
hallazgo. Cada edición es una llamada normal a update_finding hecha a través de su
cliente, por lo que requiere el alcance write, solo
se puede asignar a miembros de la organización, y un cambio rechazado se revierte en la
vista con el motivo. El interruptor de un monitor, en la lista o en el propio monitor, es una
llamada normal a set_monitor_enabled, con el mismo requisito de alcance y la misma
reversión.
Acceso. Todo se lee a través de las herramientas browse_*, así que las vistas ven
exactamente los datos de su organización bajo las mismas reglas de inicio de sesión, rol
y alcance que cualquier otra llamada a una
herramienta. Leer una transcripción o los
detalles de una conversación escribe el mismo registro de auditoría que get_transcript y
get_conversation. La estructura de un trace (spans, tiempos, modelos, tokens) se carga
con la tarjeta; lo que un span recibió y dijo (su entrada, salida, atributos y líneas de
log) puede contener lo que dijeron el usuario y el agente, por lo que solo se
lee al abrir un span o las pestañas Atributos y Logs, y cada una de esas lecturas se
audita como una lectura de transcripción. Una página de resultados de un monitor puede
citar la conversación, así que leerla escribe el mismo registro de auditoría que
get_monitor_results; el resumen, la configuración y la alerta no contienen contenido de
conversaciones y no se auditan. Los valores largos se recortan para mantener la vista ágil,
y la vista avisa cuando ocurrió. Las vistas no abren conexiones de red
propias.
Escribir herramientas
annotate_finding_conversation (añadir una anotación de audio de autoría del sistema, opcionalmente a una conversación dentro de un hallazgo) requiere un API key y el X-Organization-Id cabecera no se puede llamar con una clave org estándar. Las claves org regulares pueden escribir la misma anotación sobre REST en
POST /v1/findings/[id]/conversations/[conversationId]/comments (atribuido al usuario que llama), o leerlos a través de list_finding_conversation_comments y editar/eliminar con update_finding_conversation_comment /
delete_finding_conversation_comment.add_conversation_to_bucket add_conversation_to_finding
Devuelve la fila existente con alreadyExisted: true La conversación debe pertenecer al mismo agente que el cubo. create_bucket
acepta sólo type: "static" La creación de agente de IA ejecuta el indicador del sistema a través del flujo de auditoría antes de insertarlo.
create_finding publica un hallazgo abierto (open) en tu organización,
igual que POST /v1/findings por defecto. Los hallazgos aportados por tu propio
agente se pueden leer y ver inmediatamente en la app en todos los planes,
incluido Gratis. Esto no habilita análisis ni vinculación automática de pago.
Las llamadas MCP de administradores de plataforma conservan el flujo de revisión.
Los candidatos y rechazados existentes siguen siendo visibles sólo para staff.
Los conversationIds deben ser conversaciones de tu organización: cualquier otro id se rechaza con un error conversation_not_found que lo nombra, y no se crea nada.
La description de un hallazgo puede ser un texto plano: se admite Markdown (párrafos, listas, negrita, enlaces) y Zelto lo convierte al documento de texto enriquecido que almacena. Pasa un documento JSON TipTap/ProseMirror cuando necesites bloques que Markdown no expresa, como el bloque agentPrompt de abajo.
La description de un hallazgo puede citar la instrucción del prompt de sistema de un agente a la que se refiere el hallazgo con un bloque agentPrompt: {"type": "agentPrompt", "attrs": {"agentId": "<id del agente>", "agentName": "Paula", "agentVersionId": "<id de versión>", "versionNumber": 3, "lineStart": 12, "lineEnd": 18, "excerpt": "<líneas>"}}. El excerpt debe aparecer textualmente en el prompt de sistema de esa versión del agente (sin agentVersionId, en su prompt actual o en cualquier versión anterior), la versión debe pertenecer al agente y el agente a tu organización; de lo contrario, create_finding, update_finding y los endpoints REST rechazan la descripción. En la app, escribe / → Prompt del agente en el editor de la descripción para elegir la versión y un rango de líneas del prompt (inicio y fin).
update_agent cambios solo los campos que pases enviar description: null Para limpiarlo, omita un campo para dejarlo intacto. systemPrompt es aceptado solo para agentes de IA (los agentes humanos no tienen ninguno) y está escrito tal cual: a diferencia de la creación, es
no El tipo y el proveedor de un agente son inmutables y no se pueden cambiar.
Revisar colas
A cola es un conjunto guardado de filtros que definen una colección dinámica de conversaciones a revisar. Estas herramientas son solo MCP.
Los
filters objeto acepta: agentIds, agentType (ai / human),
durationMinSeconds, durationMaxSeconds, endedReasons, dateFrom
(YYYY-MM-DD), dateTo (YYYY-MM-DD), alreadyReviewed, hasAudio,
isInteresting, findingTypes. Un vacío/omitido filters coincide con cada conversación en la org. On update_queue, pasando filters Reemplaza todo el objeto no se fusione con la existente.
Cambios
A cambio es una sugerencia atómica, agente-alcance que se dirige a un conjunto de hallazgos. Cada nuevo cambio comienza como un proyecto (no hay estado de flujo de trabajo, oculto de la lista principal) hasta que un humano lo publique. Estas herramientas son solo MCP.Para la estabilidad de la API, los nombres de las herramientas MCP conservan el original
solution término (create_solution, list_solutions, …) aunque el producto ahora los llama cambios. Las herramientas y la interfaz de usuario operan en los mismos registros.create_solution insertos exactamente uno borrador por llamada nunca agrupe múltiples ideas en un solo cuerpo; llámelo de nuevo para cada sugerencia distinta. status es uno de backlog / todo /
in_progress / done / cancelledNo puedes establecer status sobre un borrador: salir primero del borrador con publish_solution (→ backlog) o
discard_solution (→ cancelled). Eliminar un cambio elimina sus enlaces de hallazgo por cascada, pero nunca elimina los hallazgos subyacentes.
Reportes
A informe es un analista de forma libre escrito en el mismo editor de texto enriquecido que Hallazgos y Cambios.prompt Sostiene la pregunta o breve; description mantiene el cuerpo como un documento JSON TipTap/ProseMirror.
status seguimiento del ciclo de vida de generación (pending / generating /
completed / failed) un reporte que creas se sienta en pending a menos que pases un cuerpo terminado y establecido completed. Estas herramientas son MCP-solamente.
En marcha
update_report, pasando description Reemplaza todo el cuerpo no se fusione con el documento existente. Pase prompt: null para aclarar la petición.
Población de cubo
Estas herramientas capturan las conversaciones en depósitos desde colas o filtros sin procesar.
Debido a que las colas pueden abarcar múltiples agentes, pero los depósitos están agente-scopeados,
create_bucket_from_queue crea un cubo por agente emparejado y devuelve una matriz. populate_* Las herramientas son idempotentes la re-ejecución agrega cero filas nuevas y las coincidencias que pertenecen a un agente diferente al depósito se omiten y se cuentan en skippedOtherAgentCount.
Mutaciones de cubo y Hallazgo
Las mutaciones restantes de solo MCP, más la desvinculación de conversación de Hallazgo que refleja un punto final de REST.type acepta sólo "static". Cada eliminación en cascada sus propias filas de enlaces (tareas de cubo, enlaces de conversación de Hallazgo, comentarios) pero nunca elimina las conversaciones subyacentes.
Importación de proveedores
Conecte un proveedor de voz y tire de sus agentes y conversaciones directamente a Zelto lo mismo conecte el flujo de relleno de importación → → como Configuración → IntegracionesEstas herramientas son solo MCP y cubren a todos los proveedores con capacidad de extracción: Vapi, Retell, Speechify, Telnyx AI, ElevenLabs y Kapso (WhatsApp). Cada uno toma unprovider argumento (vapi / retell / speechify / telnyx /
elevenlabs / kapso).
connect_ai_provider genera el mismo enlace de un solo uso para claves de
proveedores de IA y de transcripción. Acepta provider y label?; la clave se
introduce en Zelto, nunca en el chat. La página requiere un propietario o
administrador de la organización. Los enlaces caducan a los 15 minutos.
Para custom_openai, el formulario también solicita la URL, los modelos y las
capacidades; la validación hace una pequeña llamada de pago por modelo.
check_provider_connection devuelve kind: "ai" y status: "completed"
cuando la clave se ha validado y guardado. Después, usa list_ai_keys para
obtener su ID. Para integraciones de voz, sigue usando connect_provider
(kind: "voice"). La integración de voz de ElevenLabs y su clave STT son distintas.
connect_provider utiliza un Handoff del navegador para que la clave de la API nunca pase por el agente: devuelve una sola vez url (válido 15 minutos). Usted entrega esa URL al usuario; la abren mientras inician sesión en Zelto y pegan su clave allí, por lo que la clave va directamente al servidor, nunca a su contexto o registros. No le pidas al usuario su clave de API. Cuando terminen, poll
check_provider_connection con el retorno token hasta status es
completed (Regresa agentsFound) o expired (comienzo). label
por defecto a Default y debe ser único por proveedor; el usuario puede cambiarlo en la página de conexión.
list_provider_agents devuelve cada agente/asistente en la(s) cuenta(s) conectada(s), cada una con anotaciones alreadyImported (y importedAgentId importados). agentId es el id externo del proveedor; para Vapi y Telnyx AI es el id del asistente; para Kapso es el phone_number_id de WhatsApp (cada número es un agente; consulta Kapso).
get_retell_agent lee un agente de Retell directamente sin importarlo. Devuelve el valor actual general_prompt para los agentes de LLM Retell y global_prompt
para agentes de flujo de conversación.
import_provider_agent importa un agente y falla si ya se ha importado: llama a list_provider_agents primero. Rellena las conversaciones recientes del agente (sinceDays, por defecto 14, máx. 30) y lo inscribe en la importación automática continua, para que las nuevas conversaciones sigan llegando sin otra extracción. import_provider_conversations
importa las conversaciones de ese agente de since (una marca de tiempo ISO 8601, p. ej.
2026-03-01T00:00:00Z) hasta ahora, en segundo plano: el agente ya debe importarse y volver a ejecutarse con una ventana superpuesta es seguro (las conversaciones ya importadas se omiten).
Incorporación
Pon una nueva organización de punta a punta desde tu editor: conecta un proveedor, crea un monitor y enruta pasillos. Estas herramientas son solo MCP. El A bordo con un agente guía camina un agente a través de todo el flujo de usarlos.
Una carrera sin cabeza en orden:
get_onboarding_statusleernextIncompleteReanudar desde el paso correcto.connect_provider: genera un enlace para que un propietario o administrador introduzca la clave en Zelto. Confirma concheck_provider_connectione importa los agentes elegidos. Las instrucciones opcionales de webhook están en Configuración → Integraciones. Para claves de IA o STT, usaconnect_ai_provider. Confirma la llegada de conversaciones conlist_conversations.create_monitorpasar astarterKeyDesdelist_starter_monitors, unlibraryKeydelist_metric_library, o aname+ un booleano de lenguaje naturalinstruction. Omitir tantoagentIdscomocompanyIdslo aplica a todos los agentes actuales. Confirmar conlist_monitors. Comprobaciones de ejecución de herramientas (tool_checklo hizosubmit_orderEn realidad, el fuego es el autor Monitores editor;create_monitortodavía crea una rúbrica AI sí/no.set_findings_delivery—channels¿Es cualquiera deemail/slack(Slack también necesita la aplicación de Slack conectada a través de OAuth en la interfaz web).
get_onboarding_status devuelve los steps ordenados, cada uno con un indicador done: connectCalls (llegan conversaciones, por un proveedor conectado o por la API de ingesta), importAgent (existe un agente) y createMonitor. También devuelve nextIncomplete, el checklist sin procesar y monitorsAvailable. En un plan sin monitores (Free), createMonitor se marca como optional y blockedByPlan, nextIncomplete lo omite y complete es true cuando los demás pasos están hechos. Si existe un primer hallazgo y si la entrega está configurada no son pasos; léelos con list_findings y set_findings_delivery.
Los monitores forman parte del plan Observability. Los hallazgos aportados por tu propio agente están disponibles en todos los planes; la vinculación automática requiere Improve. En el plan Free,
monitorsAvailable es false y create_monitor responde Monitors aren't included in your organization's current plan (Free)… en lugar de crear uno. Las conversaciones, transcripciones y trazas funcionan en todos los planes.list_* / get_* leer) y devolver un objeto JSON que pueda llevar un error key inspeccione, y porque las escrituras se establecen de forma asíncrona, confirme cada paso con la herramienta de lectura emparejada antes de avanzar.
monitores y cuadros de mando
Gestionar los jueces de IA que superficie hallazgos (create_monitor /
list_monitors / list_starter_monitors están bajo Incorporación).
Usa
list_monitors para encontrar un ID y pásalo a get_monitor como
monitorId. Devuelve { monitor: { ...configuration, alert } }. El pipeline
también se resuelve para monitores antiguos; las fechas (analysisStartAt,
updatedAt) son cadenas ISO y sourceFindingId identifica el hallazgo de origen
cuando existe. alert incluye el estado habilitado, comparador, umbral, ventana,
días sostenidos, ID del canal de Slack y destinatarios de correo; es null si
no hay una alerta configurada. Nunca se devuelven claves de API; hasApiKey
indica si hay una configurada, y aiKeyId es la
clave de proveedor de IA de la organización con la que se ejecuta el monitor (null si no hay). Las lecturas no usan caché y se limitan a tu
organización. Los IDs inexistentes o de otra organización devuelven un error de
monitor no encontrado. Usa get_monitor_results por separado para consultar
los resultados de las evaluaciones y get_monitor_trends para ver cómo
evolucionan en el tiempo.
Encontrar una conversación por su ID de referencia
Para encontrar una llamada por el ID que le dio tu propio sistema o tu proveedor, pasareferenceId a list_conversations (o
GET /v1/conversations?referenceId=). Es una coincidencia exacta e indexada con
el referenceId de la conversación, así que responde rápido sin importar la
antigüedad de la llamada; después lee el transcript y la traza con el id de
conversación devuelto. Prefiérelo a un filtro meta sobre el mismo valor:
meta tiene que leer los metadatos de cada conversación, lo que es lento en una
organización de alto volumen.
createdAfter (inclusivo) y createdBefore (exclusivo) acotan la lista por
createdAt. Cada uno recibe una fecha ISO 8601 (2026-11-01, interpretada como
medianoche UTC) o una fecha y hora con desfase UTC (2026-11-01T11:30:00-03:00).
Úsalos para paginar un día o una hora en lugar de todo lo posterior. Un valor
inválido es un error (HTTP 400 en REST).
Filtrar conversaciones por metadatos
list_conversations (y GET /v1/conversations) y get_monitor_trends aceptan
meta, el mismo filtro de la página Conversaciones del panel: segmentos
key:op[:value] unidos por ; (hasta 8; todos deben cumplirse). key es una
ruta con puntos dentro de los metadatos de la conversación; usa
list_conversation_metadata_keys para ver cuáles existen. op es uno de eq,
neq, contains, not_contains, gt, gte, lt, lte (reciben un value
codificado como URI; los numéricos requieren un número) o is_set,
is_not_set, is_true, is_false. Un filtro que no se puede interpretar es
un error (HTTP 400 en REST); nunca se ignora en silencio.
Las rutas de propiedades se descubren automáticamente, incluidos campos anidados
como contexto.call_id. Para un ID guardado allí, pasa
meta: "contexto.call_id:eq:1234567890"; la igualdad compara números y booleanos por
su representación como texto. No hace falta configurar índices por organización.
Las búsquedas exactas selectivas (eq / neq) usan el índice cuando su
cobertura histórica está verificada. Los valores frecuentes y los demás operadores
conservan la consulta sobre JSON para evitar conjuntos históricos grandes. Los operadores de búsqueda parcial conservan
su comportamiento; usa una ventana de fechas para acotar historiales grandes.
Pasa companyIds a create_monitor, create_pipeline_monitor o
update_monitor para evaluar conversaciones atribuidas a las empresas seleccionadas,
incluidas las de futuros agentes. La función Empresas debe estar habilitada para
crear un alcance por empresas; los IDs deben pertenecer a tu organización y
se requiere al menos una empresa. No pases agentIds junto con companyIds.
Omitir ambos al actualizar conserva el alcance guardado; list_monitors expone
su scopeType y las companies seleccionadas. Cambiar las empresas modifica el
historial visible sin eliminar resultados guardados; las evaluaciones históricas
faltantes siguen requiriendo que actives expresamente el análisis.
Cada etapa ai_analyze de create_pipeline_monitor acepta useAgentPrompt
y useCallContext (datos CRM disponibles); ambos valen false en etapas nuevas.
Para editar el contexto, consulta los IDs con get_monitor y llama a update_monitor
con stageContext: [{ stageId: "step-id", useAgentPrompt: false, useCallContext: true }].
Cada entrada requiere un ID único de etapa de IA existente y al menos una opción
booleana; las opciones omitidas se conservan. Todos los cambios se aplican de forma
atómica. Cambiar el contexto aumenta la versión para evaluaciones futuras y reinicia
el estado de incumplimiento de alertas; conserva los resultados históricos. La respuesta
incluye version y, si se envía contexto, el pipeline actualizado.
Usa update_monitor_pipeline cuando necesites cambiar una rúbrica pero conservar
el historial del monitor. Lee el monitor con get_monitor y luego envía
instruction (una nueva rúbrica de sí/no para un monitor de una sola rúbrica) o
pipeline (la lista completa de etapas ya editada; reutiliza el id de una etapa
para que siga siendo la misma etapa). Solo puede llamarla un propietario o
administrador de la organización. El monitor conserva su ID, su alcance por agentes
o empresas, la configuración de alertas y todos los resultados guardados; cuando
cambia la puntuación, su version aumenta en uno y se reinicia el estado de
incumplimiento de alertas. La respuesta devuelve previousVersion, version, el
pipeline resuelto y headlineStageId. Editar solo las etiquetas o el tono de los
resultados no cambia la versión, y reenviar una definición idéntica no hace nada.
Los resultados existentes no se vuelven a juzgar, borrar ni recalcular, y no se
gastan créditos de modelo. Conservan la versión que los produjo, así que el
historial del monitor mezcla versiones a ambos lados del cambio; solo las
conversaciones evaluadas después de la edición usan la nueva rúbrica.
get_monitor_results devuelve resultados de todas las versiones, mientras que las
vistas por versión de la interfaz de Monitores los mantienen separados. Para
evaluar conversaciones pasadas con la nueva rúbrica, ejecuta un análisis histórico
desde la interfaz de Monitores (esto sí gasta créditos). Los monitores de audio no
tienen un pipeline de etapas y no se pueden editar así.
Flujo de trabajo de Hallazgos
Más allácreate_finding / update_finding, estos impulsan el ciclo de vida abierto y el dedup de → candidato.
Todo en esta tabla, excepto
set_finding_version_scope requiere el owner
o admin El rol, como delete_finding y renombrando a través update_finding
Véase Tu papel decide lo que puedes hacer.
Revisión de conversaciones
flag_call_for_review solo pone en cola una conversación; estos registran la revisión real.
agentes (ciclo de vida)
create_ai_agent / create_human_agent / update_agent más:
merge_agents / unmerge_agents También existen pero requieren una clave de administrador (cross-org), que coincida con las herramientas de fusión solo de personal en la interfaz de usuario web.
Receptores (números de teléfono)
Integración & conectores
El proveedor conecta/importa bajo Importación de proveedores. Estos configuran una integración ya conectada.
Slack (post-connect; la instalación de OAuth permanece en la interfaz web):
add_slack_channel,
remove_slack_channel, set_default_slack_channel,
set_slack_channel_chat_enabled, send_slack_channel_test,
set_agent_slack_channel cada uno toma un identificador de canal de Slack (C…), y
set_agent_slack_channel También un agentId.
Linear (post-connect; la instalación de OAuth permanece en la interfaz web):
list_linear_teams, set_default_linear_team (teamId, nullable),
create_linear_issue_for_finding (findingId),
create_linear_issue_for_solution (solutionId), unlink_linear_issue
(findingId? / solutionId?).
Claves de proveedores de IA
Las claves propias de la organización (trae tu propia clave) de Configuración → Proveedores de IA. Todas estas herramientas son solo para propietarios o administradores, y todas salvolist_ai_keys requieren el
alcance write. El secreto es de solo escritura: se comprueba con una llamada
sin costo al proveedor antes de guardarlo cifrado, y las respuestas solo incluyen
lastFour.
Un éxito devuelve
{ key }. Un error devuelve { error, code }, donde error
es un mensaje legible y code es invalid_input, invalid_key (el
proveedor la rechazó), provider_unreachable, duplicate_label, not_found,
in_use o phi_mode_blocked. Pasa el id de una clave como aiKeyId a
test_monitor para probar un monitor con ella, y luego a set_monitor_model
(con el id model del proveedor) para poner un monitor guardado en ella.
Organización & Miembros
upload_conversation cobra un crédito de conversación, como cualquier carga. Una conversación de voz también necesita durationSeconds (mayor que 0, como máximo 31536000) para analizarse, porque los minutos del plan se miden con él; para un chat, indica en su lugar channel como text, chat, web-chat, sms, whatsapp o in-app, que no consume minutos de voz. El campo analysisSkipReason de la respuesta (plan_limit o no_duration) y su message explican por qué una conversación guardada no se analizó. Una conversación necesita al menos 4 turnos para analizarse; una más corta se guarda y se puede leer, pero el flujo de análisis la omite (sin resumen, hallazgos ni resultados de monitores). Para enviar conversaciones desde tu propio código en lugar de una a una, envíalas por POST al endpoint de ingesta con la misma clave.
Todas las herramientas de esta tabla excepto upload_conversation requiere el owner o
admin papel, y update_member_role requiere owner Véase Tu papel decide lo que puedes hacer.
Las entradas anteriores son los campos primarios; el servidor MCP anuncia el esquema completo y autorizado para cada herramienta a través de tools/list.
Las entradas de correo electrónico utilizan patrones de esquema JSON en lenguaje regular, por lo que los esquemas de herramientas anunciados siguen siendo compatibles con proveedores de salida estructurada estrictos, incluido OpenAI.
Formas de salida y paginación
Las respuestas de la herramienta coinciden exactamente con la API REST. Referencia API para las formas JSON deAgent,
Conversation, Transcript, Review, Bucket, y Finding, más el { data, nextCursor } sobre de paginación.
limit 200 (por defecto 50). cursor es opaco devolver el
nextCursor valor de una respuesta anterior para buscar la página siguiente. Un
cursor que la API no emitió es un resultado de error con código
invalid_parameter (parameter: "cursor"), igual que en REST, nunca un reinicio
silencioso desde la página 1.
Las conversaciones de list_conversations y get_conversation incluyen
analysisStatus: analyzed, pending, skipped_too_short (menos de 4 turnos),
skipped_plan_limit (más larga que los minutos mensuales que quedaban cuando
llegó), skipped_no_duration (una conversación de voz enviada sin duración) o
unknown. Así un agente que sube más de lo que permite el plan puede saber que
una conversación se guardó pero no se analizó. Pueden añadirse valores nuevos;
trata uno que no conozcas como “aún sin analizar”.
Resultados de error
Un rechazo es un resultado conisError: true y un cuerpo JSON que siempre
incluye error, y además code, message y hint cuando hay un siguiente
paso: not_found (un id que no está en tu organización: las herramientas
get_*, browse_* y las de monitores lo responden, con una pista que nombra la
herramienta que lista ids válidos), invalid_parameter, not_entitled (el plan
no incluye la función; la pista indica dónde mejorar) y not_enabled. En tu
código usa code, no el texto de message. Las herramientas browse_* que
alimentan las vistas interactivas conservan su forma vacía (por ejemplo
conversation: null) junto a los campos de error cuando el id no existe.
Solución de problemas
401de cada herramienta el token portador está equivocado o revocado. Pruebe la clave directamente:curl -H "Authorization: Bearer $ZELTO_API_KEY" https://api.zelto.ai/v1/agents. Si eso también regresa401, menta una nueva llave.This credential is read-only and cannot call "<tool>".— al token OAuth solo se le concedió el alcanceread. Vuelva a conectar y concedawrite, o use una clave API. Vea Alcance de lectura y escritura.400conBatched tool calls are not supported— el cliente envió un array JSON-RPC. Envíe un mensaje porPOST.Only an organization owner or admin can perform this action.la herramienta funcionó, tu rol no. Tu credencial se resuelve en lamemberPídale a un propietario o administrador que lo ejecute o que eleve su rol; vea la sección de la sección de administración de la página. Tu papel decide lo que puedes hacer.- La lista de herramientas está vacía en el cliente la mayoría de los clientes almacenan en caché la lista de herramientas. Reiniciar el cliente (Claude Code:
/mcp; Cursor: activar/desactivar el servidor; Codex: reiniciar la CLI). 429tasa limitada retroceder y volver a intentarlo. Utilice elcursorpaginación en lugar de buscar páginas grandes.- Acceso a Cross-org denegado las claves están incluidas en la organización en la que fueron acuñadas. Cambiar de organización en la aplicación web y acuñar una nueva clave de esa organización Configuración → Integraciones.
Acceso a grabaciones
Los campos de URL de grabación apuntan a rutas de reproducción autenticadas. Envía la misma clave de API de la organización o token OAuth al solicitar audio; el navegador requiere una sesión con membresía vigente. Esto se aplica a las grabaciones mixtas y multicanal. Las grabaciones almacenadas por Zelto redirigen a URL firmadas que caducan a los 15 minutos. Sigue la redirección para reproducir o descargar; cuando caduque, solicita de nuevo la ruta autenticada original. Las URL públicas históricas dejan de funcionar al activar el almacenamiento privado. Conexiones compatibles con OpenAI:create_ai_key acepta provider: "custom_openai" y customConfig con baseUrl, models explícitos y las opciones streaming, tools y structuredOutput. Una solicitud sintética por modelo valida la conexión y puede generar cargos del proveedor. Consulta Proveedores de IA.
Tickets de soporte
Tu agente puede crear tickets, consultar su estado y añadir comentarios. Los tickets aparecen en Soporte en el panel de tu organización. Las herramientas solo acceden a la organización autenticada y nunca muestran comentarios internos.
Crear tickets y comentar requiere permiso de escritura. Cualquier miembro de la
organización puede hacerlo. El estado se sincroniza desde el sistema de soporte.
Incluye referencias de error y pasos para reproducirlo, nunca claves API ni datos
sensibles de llamadas. Si una escritura falla de forma ambigua, consulta los
tickets o el historial antes de reintentar para evitar duplicados.
Feedback de agentes
Cuando falta una capacidad o una herramienta bloquea la tarea, tu agente puede avisar al equipo de Zelto consend_feedback. A diferencia de un ticket de
soporte, el feedback no recibe respuesta ni se guarda; llega a un canal interno.
Cualquier credencial puede usarla, incluido un token OAuth con alcance
read, y
cualquier miembro de la organización puede hacerlo. Comparte con el endpoint REST
el límite de 5 intentos por organización por minuto. Usa solo ejemplos
sintéticos, reporta cada problema una vez y no reintentes automáticamente.
Consulta Feedback de agentes.
El servidor invita a dar feedback en dos lugares: las instrucciones que recibe el
cliente al conectarse (initialize) y cada llamada a herramienta que falla. Un
resultado de error recibe un texto adicional y un campo feedback en
structuredContent; un error JSON-RPC (por ejemplo Tool <name> not found)
recibe la invitación al final de su message y en data.feedback. Los
resultados correctos no cambian, y los errores de send_feedback nunca incluyen
la invitación.
Estado de uso
Usaget_usage_statement (solo lectura, month opcional como AAAA-MM) para
leer qué se le cobra a tu organización en un mes. Refleja
GET /api/v1/usage/statement y la página Configuración → Uso: los importes
están en micro-USD, con cada concepto como cantidad y precio unitario, el nivel
por volumen, el crédito gratuito, la proyección a fin de mes, el límite de gasto
en IA y el precio de cada unidad en cada nivel. La herramienta siempre usa la
organización autenticada. Consulta
Planes y límites para ver cómo
funcionan los niveles.
Desglose del uso de IA
Usaget_ai_usage_breakdown (solo lectura, month opcional como AAAA-MM) para
ver en qué se usó la IA de tu organización en un mes. Refleja
GET /api/v1/usage/ai y el desglose de Uso de IA al costo en
Configuración → Uso. El total es el uso de IA al costo del mes, y el mismo
monto se desglosa por monitor, por actividad (monitores sobre llamadas,
backfills, configuración, procesamiento de llamadas, asistentes, simulaciones),
por modelo (tokens de entrada y salida, y la tarifa actual por 1M de tokens) y
por día. Cada fila incluye las llamadas al modelo y, aproximadamente, en cuántas
llamadas se usó. Los importes están en micro-USD.
Facturas y enlaces de pago
Usalist_invoices (solo lectura, sin argumentos) para listar las facturas
recientes de tu organización en Stripe y Mercury. Refleja
GET /api/v1/billing/invoices y las facturas de Configuración → Facturación.
Usa create_invoice_payment_link (escritura, solo propietarios y administradores, invoiceId de list_invoices) para
obtener un enlace a una factura de Stripe abierta o pagada que puedes enviar a
quien la paga. La página no requiere iniciar sesión y muestra solo esa factura,
sus líneas y, en los acuerdos que cobran la IA al costo, en qué se usó la IA,
más un botón Pagar. Cualquier persona con el enlace puede ver la factura, y vence
a los 30 días. Refleja POST /api/v1/billing/invoices/{invoiceId}/payment-link y
Compartir enlace en Configuración → Facturación.
Saldos compartidos de Free
get_free_budgets es de solo lectura y no recibe argumentos. Muestra los saldos
mensuales de USD 5 de IA y USD 5 de observabilidad de tu organización, igual que
GET /api/v1/usage: valores en microdólares USD, usados, reservados, disponibles y
renovación UTC. freeBudgets: null indica que el contrato está inactivo o que el
plan es pago. No permite consultar otra organización. Ver Planes.
Las claves de Google Gemini (provider: "google") permiten ejecutar candidatos y jueces LLM en Benchmarks. Agrega la clave con connect_ai_provider y selecciona su aiKeyId para la ejecución del benchmark. No se admiten claves Google en test_monitor ni en set_monitor_model.
