Saltar al contenido principal
Zelto expone un Protocolo de contexto modelo servidor en 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 es zelto-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úblico https://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 en https://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:
La base REST es 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:
Si usted pertenece a más de una organización, usted elige a cuál de las conexiones está enfocada en la pantalla de consentimiento el cliente solo ve los datos de esa organización, exactamente como una organización enfocada en el ámbito de la organización. Clave APILos tokens de acceso duran poco (una hora), se actualizan solo mientras la sesión de Zelto es válida y dejan de funcionar tan pronto como pierde el acceso a esa organización. Bajo el capó, el servidor es un servidor de autorización OAuth 2.1 estándar como lo define la especificación MCP: publica Metadatos de recursos protegidos, admite el registro dinámico de clientes y requiere PKCE para que un cliente compatible descubra todo lo que necesita solo desde la URL. Las claves de API siguen funcionando en paralelo; use lo que su cliente admita.
¿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):
Reiniciar Claude Code (o ejecutar /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]:
Luego corre 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:
A continuación, abra el panel MCP del cursor y cambie el 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:
Zed utiliza ~/.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:
A 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 un Authorization: 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 la owner 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. Implica read.
  • read — solo las herramientas de lectura. Un token con alcance read que 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 es send_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.
Las claves API tienen acceso completo; una clave no se restringe por alcance. Sea cual sea la credencial, la restricción por rol (Tu papel decide lo que puedes hacer) se aplica además. Envíe un mensaje JSON-RPC por cada 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 herramienta browse_* 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 view de show_trace elige 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.
En pantallas angostas la lista de spans y el detalle se turnan, con una forma de volver. Lista de monitores. Lo que muestra la página de Monitores: cada monitor en el orden que usted lo ordenó, con su estado, los agentes o empresas a los que aplica, sus etapas y la tasa de afectación en una ventana de 24 horas o 7, 15 o 30 días, con las palabras de resultado del propio monitor (por ejemplo “reembolso prometido”). Pestañas de estado con contadores, búsqueda, un filtro por agente y el orden la acotan. Los argumentos eligen cómo se abre, por ejemplo { "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_alert para cambiarla.
Los argumentos 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.
Idempotente: 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 un provider 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.
Nunca acepte una clave de API de proveedor como argumento de herramienta, ya que se capturaría en los registros de conversación y cliente del agente. connect_provider es un traspaso exactamente por esta razón: la clave solo viaja al servidor → del navegador.
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:
  1. get_onboarding_status leer nextIncomplete Reanudar desde el paso correcto.
  2. connect_provider: genera un enlace para que un propietario o administrador introduzca la clave en Zelto. Confirma con check_provider_connection e importa los agentes elegidos. Las instrucciones opcionales de webhook están en Configuración → Integraciones. Para claves de IA o STT, usa connect_ai_provider. Confirma la llegada de conversaciones con list_conversations.
  3. create_monitor pasar a starterKey Desde list_starter_monitors, un libraryKey de list_metric_library, o a name + un booleano de lenguaje natural instruction. Omitir tanto agentIds como companyIds lo aplica a todos los agentes actuales. Confirmar con list_monitors. Comprobaciones de ejecución de herramientas (tool_check lo hizo submit_order En realidad, el fuego es el autor Monitores editor; create_monitor todavía crea una rúbrica AI sí/no.
  4. set_findings_delivery — channels ¿Es cualquiera de email / 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.
Estos son escribir herramientas (excepto la 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, pasa referenceId 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 salvo list_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.
Si una persona puede pegar la clave, usa la página Configuración → Proveedores de IA: por MCP, el secreto pasa por la conversación del agente y los registros de su cliente.

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 de Agent, 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 con isError: 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

  • 401 de 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 regresa 401, menta una nueva llave.
  • This credential is read-only and cannot call "<tool>". — al token OAuth solo se le concedió el alcance read. Vuelva a conectar y conceda write, o use una clave API. Vea Alcance de lectura y escritura.
  • 400 con Batched tool calls are not supported — el cliente envió un array JSON-RPC. Envíe un mensaje por POST.
  • Only an organization owner or admin can perform this action. la herramienta funcionó, tu rol no. Tu credencial se resuelve en la member Pí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).
  • 429 tasa limitada retroceder y volver a intentarlo. Utilice el cursor paginació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 con send_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

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

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

Usa list_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.