Skip to main content

​
Crear una clave

  1. Abre Configuración → Integraciones → Carga de llamadas 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 }. 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 llamada con un agente que ya exista en el panel. 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 llamada, 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 llamadas 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 llamada. 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 llamadas, 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 llamada. 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 llamada 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 llamada, por lo que un agente compartido puede atender llamadas consecutivas para empresas distintas:
Utiliza el mismo valor estable para todas las llamadas 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 llamadas posteriores. Si omites el campo, Zelto utiliza la empresa predeterminada del agente, si existe; de lo contrario, la llamada 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 llamadas 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 llamada —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 llamada 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 llamada aparece en Conversaciones.Una entrega sin transcripción ni grabación se considera una llamada no conectada. Zelto responde con 200, pero no crea una conversación porque no hay nada que transcribir o analizar. Envía la llamada 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. Envía la llamada 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 llamada

Después de la primera solicitud, abre Conversaciones. La llamada 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 llamada no aparece, revisa la respuesta: { "received": true } indica que Zelto la aceptó 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