Saltar al contenido principal
Zelto ingiere conversaciones de texto —de chatbots, agentes de mensajería o cualquier asistente basado en texto, como chat web, SMS, WhatsApp o chat dentro de la aplicación— mediante el mismo endpoint que las llamadas de voz: POST https://ingest.zelto.ai/webhooks/calls. Una conversación de texto es una conversación con transcripción y sin audio. Como la transcripción ya existe, Zelto omite ese paso; todo lo demás —resúmenes, hallazgos, revisiones e informes— funciona igual que con una llamada de voz. La creación de claves, la idempotencia y la gestión de errores se comparten con Proveedores personalizados y otros. Esta página explica únicamente lo específico de las conversaciones de texto.
¿Tu agente está construido sobre Kapso? Usa la integración nativa de Kapso: conecta la clave de API del proyecto y Zelto importa tus números de WhatsApp y sus conversaciones sin código de carga.

Crear una clave

Las cargas de texto utilizan la misma clave de API que cualquier otra carga personalizada. Sigue los pasos de Proveedores personalizados y otros → Crear una clave en Configuración → Integraciones → Integración por API y expón la clave como ZELTO_API_KEY.

Subir una conversación de chat

Envía los mensajes en transcript.turns: utiliza role: "user" para la persona y role: "assistant" para el agente. Omite los campos de audio y telefonía. Solo son obligatorios call.externalId y una referencia al agente.
chat.json
Una carga correcta devuelve HTTP 200 con { "received": true }. Campos que debes enviar:
  • agent.externalId, para que Zelto busque o cree el agente, o agentId, el UUID de un agente existente. Utiliza un identificador estable por agente, no por conversación.
  • call.externalId, un identificador único y estable para la conversación y la clave de idempotencia.
  • transcript.turns[], los mensajes en orden como turnos user y assistant. Envía al menos 4 si quieres que la conversación se analice; las más cortas se guardan y aparecen en la lista, pero no reciben resumen ni hallazgos.
  • call.startedAt y call.endedAt, las horas de inicio y fin en ISO 8601. Son opcionales, pero permiten ordenar y filtrar por hora.
  • metadata.channel, para guardar el canal (web-chat, sms, whatsapp o in-app) y poder filtrarlo después. No existe un campo específico para el canal.
Campos que debes omitir:
  • recordingUrl y recordingUploadId, porque no hay audio que volver a alojar.
  • startSeconds, endSeconds y words[] por turno, ya que solo se utilizan para reproducir una transcripción sincronizada con audio.
  • durationSeconds y customer.number cuando no tengan un equivalente útil en la conversación de texto.
Una entrega sin transcripción ni grabación se considera una conversación vacía. Zelto responde con 200, pero no crea una conversación porque no hay nada que analizar. Una conversación de texto debe incluir al menos un elemento en transcript.turns.

Invocaciones de herramientas

Si el chatbot invoca herramientas durante la conversación, por ejemplo para consultar disponibilidad o buscar un pedido, envía cada invocación como un turno tool con un objeto toolCall, igual que para un agente de voz. Zelto la muestra en la transcripción y la incluye en el análisis. Consulta Invocaciones de herramientas para ver los campos y un ejemplo.

Cargas repetidas idempotentes

call.externalId es la clave de idempotencia. Si vuelves a enviar el mismo identificador, Zelto actualiza la conversación existente y nunca la duplica. Por eso, tanto los reintentos como los reenvíos posteriores de enriquecimiento son seguros. Consulta Cargas repetidas idempotentes.

Nombres y etiquetas de canal

Las conversaciones de texto se ingieren y analizan por completo. El nombre de una conversación se genera por defecto a partir de su externalId, salvo que envíes un name más descriptivo. Tampoco existe todavía un campo de modalidad o canal de primer nivel: el valor de metadata se guarda y se puede consultar, pero la interfaz no identifica la conversación como chat. Todas las funciones de análisis funcionan igual que con voz.

Contenido relacionado

  • Proveedores personalizados y otros — contrato compartido de carga, claves, errores y cargas nativas de Vapi y Retell.
  • Conversaciones — dónde aparecen las conversaciones cargadas.
  • Referencia de API — convenciones REST, formato completo y área de pruebas.
  • MCP — utiliza la misma clave para ofrecer acceso de lectura y escritura a editores conectados.