SDK de TypeScript
El paquete oficial de npm eszelto-sdk. El envío de conversaciones se incorpora en 0.4.0;
0.3.0 solo ofrece la API anterior de analítica web. Consulta npm view zelto-sdk version
antes de instalar. Si 0.4.0 no está disponible, usa el ejemplo HTTP de esta guía.
stored: true significa aceptado para procesamiento asíncrono. Verifica la llegada
en Conversaciones o por REST/MCP. Menos de cuatro turnos se almacenan sin análisis.
Para otro entorno, pasa la URL completa endpoints.ingestCalls del bootstrap como
ingestUrl; el valor predeterminado es https://ingest.zelto.ai/webhooks/calls.
Usa la clave API de la organización, no ingestKey de OpenTelemetry.
Espera el envío desde una tarea persistente. El SDK tiene un timeout de 10 segundos
(configurable con timeoutMs) y no reintenta automáticamente. Reintenta errores de
red, 429 y 5xx con la espera progresiva de tu cola, el mismo payload completo y
call.externalId. Corrige otros errores 4xx antes de reintentar. Reenviar un ID
reemplaza su conversación. Los errores HTTP lanzan ZeltoApiError con status y
details; estos pueden incluir datos sensibles, así que evita registrarlos.
Maneja stored: false incluso con HTTP 200. Los exports existentes zelto.init /
track / identify son para analítica web; usa
new Zelto(...).sendConversation(...) para conversaciones de agentes IA.
Crear una clave
- Abre Configuración → Integraciones → Integración por API y haz clic en Crear clave de API.
- Asigna un nombre descriptivo, por ejemplo
prod-twilio-uploader. - Copia la clave una sola vez. Zelto solo guarda su hash.
owner o admin. Una clave permite leer todas las conversaciones de la
organización, así que no es una credencial para un miembro individual.
Configurar con un agente de codificación
¿Prefieres no implementar la conexión a mano? Pega el siguiente mensaje en el agente de programación de tu editor, como Claude Code, Cursor o Codex. El mensaje remite a esta guía y a la referencia de API, describe el contrato completo y pide al agente que siga las convenciones de tu base de código. Tú debes proporcionar la clave: créala arriba y expónla comoZELTO_API_KEY. El mensaje indica que debe leerla desde el entorno
y que nunca debe incluirla directamente en el código.
Pega esto en tu agente de programación
Subir una conversación
Envía toda la conversación —agente, transcripción, grabación opcional y metadatos— en una sola solicitud POST a/webhooks/calls. Zelto confirma la
recepción inmediatamente y crea la conversación y la transcripción en segundo
plano. La pestaña Referencia de API explica las convenciones REST e incluye un
área de pruebas para validar una carga útil antes de utilizarla en producción.
El ejemplo siguiente representa una llamada de voz. Para una conversación de
texto se utiliza el mismo formato sin los campos de audio.
call.json
200 con { "received": true, "stored": true }.
El cuerpo 200 también indica lo que Zelto decidió al recibir la solicitud. Todos
los campos salvo received son opcionales, así que sigue ignorando los campos
desconocidos:
Zelto solo analiza una conversación si
transcript.turns tiene al menos 4
turnos. Una más corta (colgó al instante, una prueba de una línea) se guarda
y aparece en Conversaciones, pero no recibe resumen ni hallazgos y no se
factura. Si tu primera conversación de prueba aparece sin análisis, envía una
con cuatro turnos o más.Zelto decide si una conversación cabe en los minutos mensuales de tu plan
después de responder
200, así que la respuesta es la misma dentro y fuera de
la cuota y no tiene ningún campo para ello. Una conversación se analiza solo si
toda su duración cabe en los minutos que quedan del mes; una que no cabe se
guarda y se puede leer, pero no se analiza, mientras que una más corta que sí
cabe se analiza. Las omitidas aparecen como Sin analizar en
Conversaciones y en sus detalles, y la pestaña Uso las cuenta. Una conversación de voz enviada sin
call.durationSeconds también se guarda sin analizarse hasta que se registre
una duración. Consulta Planes.Los minutos se cuentan una sola vez. Si reenvías un call.externalId con un
call.durationSeconds mayor, solo se cuentan los minutos añadidos (y deben
caber en lo que queda de tu plan, como una conversación nueva); si no caben,
el reenvío actualiza igualmente la transcripción, pero la duración se queda
en lo que ya se contó. Una duración menor o igual no cambia nada. Una
conversación de voz enviada con duración 0 se trata como si no tuviera
duración. Una conversación con grabación es de voz sea cual sea su metadato
channel; solo la que no tiene audio cuenta como texto.analysisStatus en GET /v1/conversations (cada elemento) o
GET /v1/conversations/{id}, o en las herramientas MCP list_conversations y
get_conversation:
Pueden añadirse valores nuevos; trata cualquier valor que no conozcas como
“aún sin analizar”.
Solo son obligatorios
call.externalId y una referencia al agente. Utiliza
agent.externalId para que Zelto busque o cree el agente, o agentId para
asociar la conversación con un agente que ya exista en el panel. Si creaste el
agente a mano, envía su agentId: otro agent.externalId crea un segundo agente. Si incluyes
call.recordingUrl, Zelto vuelve a alojar el audio para que el reproductor siga
funcionando después de que caduque la grabación original.
Utiliza version para identificar la compilación del agente o la revisión del
prompt que atendió la conversación, por ejemplo "v3". Zelto la guarda como la versión
del agente para que puedas comparar el rendimiento entre versiones. El campo es
opcional y funciona con cualquiera de las referencias al agente. Envía siempre
la misma cadena para las conversaciones de una misma compilación.
Enviar la configuración del despliegue
EnvíaversionConfig opcional en el nivel superior junto con version para registrar todo lo que usa el despliegue. Es un objeto JSON de hasta 64 KiB; llm, stt y tts son nombres convencionales, y se conservan herramientas, flujos, ejecución y campos propios. Este contexto es independiente de metadata por conversación. Se captura al crear y no reemplaza una captura existente. Consulta Versiones de agentes para el formulario, la API y un ejemplo completo.
Contrato de versiones para experimentos
Para atribuir correctamente las conversaciones, incluyeversion en cada carga
de cada despliegue. Es una cadena de 1 a 255 caracteres, sin espacios en los
extremos y sensible a mayúsculas. El mismo agente y etiqueta reutilizan una
versión; una etiqueta nueva la crea al procesar su primera conversación. Cámbiala
al modificar el pipeline o prompt. metadata.version no asigna la versión.
Conserva el ID del agente entre despliegues e indica la versión que atendió la
sesión, junto con su systemPrompt y configuración capturada. La detección
automática basada en prompts no distingue de inmediato despliegues simultáneos
ni cambios exclusivos del pipeline.
Consulta Versiones de agentes para ver ejemplos,
límites de capturas, comportamiento por proveedor, reintentos y verificación.
Atribuir cada conversación a una empresa
Si tu organización gestiona agentes para varios clientes o marcas, envíacompanyExternalId en el nivel superior. La atribución se realiza por conversación,
por lo que un agente compartido puede atender conversaciones consecutivas para empresas
distintas:
Grupos de agentes
Envíaagent.groups para organizar agentes relacionados, por ejemplo por área,
idioma, equipo o campaña. Cada nombre representa un grupo; Zelto lo busca o lo
crea en la organización y añade el agente. Un agente puede pertenecer a varios
grupos y el campo es aditivo: una carga posterior nunca elimina un grupo
existente. Los grupos permiten filtrar todos los informes y la
lista de conversaciones. También puedes administrarlos
manualmente desde la configuración del agente.
Un grupo no atribuye conversaciones a una empresa. Utiliza
companyExternalId para
un cliente o una marca, y agent.groups para organizar agentes con flexibilidad.Invocaciones de herramientas
Si el agente invoca herramientas durante la conversación —por ejemplo, para consultar disponibilidad, reservar una cita o buscar un pedido—, envía cada invocación como un turnotool con un objeto toolCall. Zelto la muestra en la transcripción, la
registra como una traza de invocación de herramienta
consultable y utiliza su nombre, argumentos y resultado en los análisis de IA.
Envía la conversación una sola vez como datos estructurados; no necesitas volver a
representarla manualmente en content.
Un toolCall tiene la forma { name, arguments?, result?, status?, toolCallId?, errorMessage? }; solo name es obligatorio. arguments y result aceptan
cualquier valor JSON; status puede ser success, error o pending; y
toolCallId relaciona una invocación con su resultado si los envías en turnos
separados. content puede quedar vacío cuando existe toolCall, porque Zelto
utiliza el nombre de la herramienta como etiqueta. startSeconds lo coloca en la
línea de tiempo.
Conversaciones de texto y mensajería
El mismo endpoint admite conversaciones de texto de chatbots o agentes de mensajería, como chat web, SMS, WhatsApp o chat dentro de la aplicación. Envíatranscript.turns y omite los campos de audio y telefonía, ya que no existe una
grabación que volver a alojar. Consulta
Chatbot y conversaciones de texto
para ver el contrato completo y un ejemplo de chat.json.
Manejar errores
Los errores se devuelven como JSON con una cadenaerror. Los errores de
validación y del proveedor también incluyen un objeto details con lo que debes
corregir.
Una respuesta
200 significa que Zelto aceptó la carga, no que haya terminado
de procesarla. Los problemas de autenticación y los cuerpos mal formados fallan
inmediatamente con 4xx, pero un problema semántico —como un agentId que no
existe en la organización— puede devolver 200 y fallar después. Para evitarlo,
utiliza agent.externalId, que busca o crea el agente, y confirma que la conversación
aparece en Conversaciones.Una entrega sin transcripción ni grabación se considera una conversación no
conectada. Zelto responde con 200, pero no crea una conversación porque no hay
nada que transcribir o analizar. Envía la conversación cuando dispongas de una
transcripción o de recordingUrl; también puedes hacer un
reenvío de enriquecimiento más adelante.Cargas repetidas idempotentes
call.externalId es la clave de idempotencia. Si vuelves a enviar el mismo
identificador, Zelto actualiza la conversación existente —grabación,
transcripción, duración o costo— y nunca la duplica. La transcripción se
reemplaza, no se combina: un reenvío con menos turnos sobrescribe al más
largo. La respuesta 200 lo indica con "updated": true y "previousTurns". Envía la conversación al finalizar
y vuelve a enviarla después si añades información, por ejemplo cuando termine de
subirse la grabación.
¿Ya estás en Vapi o Retell?
El mismo endpoint también acepta las cargas útiles nativas de los webhooks de Vapi y Retell. Configura la cabeceraX-Zelto-Provider como vapi o retell y
envía el cuerpo del proveedor sin modificarlo. Omite la cabecera o utiliza
zelto para enviar el formato canónico anterior.
Verificar la primera conversación
Después de la primera solicitud, abre Conversaciones. La conversación debería aparecer con su transcripción en pocos segundos. El área de pruebas de Referencia de API es la forma más rápida de enviar una carga de ejemplo. Si la conversación no aparece, revisa la respuesta:{ "received": true, "stored": true }
indica que Zelto la aceptó (con "stored": false, reason explica por qué no se guardó nada) y una respuesta 4xx explica el motivo, como un valor
incorrecto de X-Zelto-Provider, un campo no válido o una clave incorrecta.
Consulta
Conectar un proveedor de voz.
Cuándo usar esto vs una integración nativa
Si ya utilizas Vapi o Retell, elige la integración nativa: recibe los webhooks y obtiene las grabaciones automáticamente. Esta guía sirve para todo lo demás, como Bland, Pipecat, agentes de texto o mensajería, plataformas internas o cualquier proveedor sin una integración dedicada. Para LiveKit, consulta su guía específica.Relacionado
- Chatbot y conversaciones de texto — el mismo endpoint para texto, sin audio.
- Conectar un proveedor de voz — elige el método adecuado.
- LiveKit — el mismo endpoint con un ejemplo para un worker.
- Referencia de API — convenciones REST y formato completo de la solicitud.
- Conversaciones — dónde aparecen las conversaciones cargadas.

