Saltar al contenido principal

SDK de TypeScript

El paquete oficial de npm es zelto-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.
Ejecuta este código en una tarea de servidor con Node.js 18+ cuando termine la conversación. Nunca expongas la clave de la organización en código del navegador ni en una variable de entorno pública.
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

  1. Abre Configuración → Integraciones → Integración por API y haz clic en Crear clave de API.
  2. Asigna un nombre descriptivo, por ejemplo prod-twilio-uploader.
  3. Copia la clave una sola vez. Zelto solo guarda su hash.
La tarjeta muestra las claves activas y la última vez que se utilizaron. Puedes eliminar una clave en cualquier momento para revocar el acceso inmediatamente. Para crear o revocar claves necesitas el rol 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 como ZELTO_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
Si tu editor tiene conectado el servidor MCP de Zelto, el agente puede utilizar read_docs para consultar siempre la versión actual del contrato. La misma clave sirve para MCP, la API REST y este flujo de carga.

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
Una carga exitosa devuelve HTTP 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.
Para comprobar desde código si una conversación guardada se analizó, lee su 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ía versionConfig 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, incluye version 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ía companyExternalId 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:
Utiliza el mismo valor estable para todas las conversaciones de una empresa. Cuando la función Empresas está activada, el primer valor desconocido crea una empresa temporal con ese nombre. Puedes cambiarlo en el panel sin alterar la asignación de las conversaciones posteriores. Si omites el campo, Zelto utiliza la empresa predeterminada del agente, si existe; de lo contrario, la conversación queda sin atribuir. Consulta Empresas para entender el modelo y Configurar empresas para seguir los pasos en el panel.

Grupos de agentes

Envía agent.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 turno tool 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ía transcript.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 cadena error. 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 cabecera X-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