Sincroniza tus llamadas con la API

Sincroniza tus llamadas con la API

Tus propios sistemas pueden seguir cada llamada: un webhook que avisa en tiempo real, un historial paginado para cargar y reconciliar, grabaciones y transcripciones por identificador de llamada, y clic para llamar desde tu CRM. Endpoints, encabezados, ejemplos con curl y un patrón de sincronización.

Qué puedes hacer

La API de Integraciones Privadas permite que tus propios sistemas trabajen con tus llamadas de Zonitel: recibir un evento en el momento en que ocurren, descargar el historial de llamadas de forma programada, obtener la grabación y la transcripción de una llamada, y lanzar una llamada desde un botón en tu CRM. Todas las peticiones de esta guía se hacen contra https://api.zonitel.com/api/v3.

Si todavía no has creado una credencial de acceso, empieza por la guía de Integraciones Privadas y luego vuelve aquí.

Antes de empezar

Cada petición lleva dos valores de la pestaña Credenciales en Configuración > Integraciones Privadas: tu token y tu identificador de cliente. Viajan como encabezados.

Authorization: Bearer TU_TOKEN
X-Client-Id: TU_CLIENT_ID
Accept: application/json

El detalle completo de parámetros y respuestas de cada endpoint está en la referencia interactiva de la API, y en la pestaña Resumen de esa misma pantalla encontrarás una colección de Postman lista para usar.

Dos formas de llevar las llamadas a tu sistema

Webhook: te llega solo, en tiempo real

Registras una dirección y enviamos un evento a ella a medida que ocurren las llamadas. El contenido documentado trae el nombre y el número de quien llama y el número marcado, suficiente para abrir una ficha o buscar al cliente antes de que alguien conteste. Tu servidor tiene cinco segundos para responder HTTP 200, y la dirección debe ser HTTPS y accesible desde internet. Incoming Call Webhooks detalla el contenido del evento y las respuestas de error.

Historial: lo consultas tú, cuando quieras

Una lista paginada y filtrada por fecha de las llamadas anteriores. El webhook te avisa de que una llamada empieza; el historial es donde está la foto completa y de donde sale el identificador con el que se piden la grabación y la transcripción. Sírvete de él para cargar el histórico al conectar y para reconciliar después: si tu servidor estuvo inaccesible una hora, así recuperas lo que se perdió. La mayoría de las integraciones usan los dos.

No existe un endpoint que liste las llamadas en curso. Todo lo que es tiempo real llega a tu sistema por el webhook. Si lo que quieres es una vista en vivo para tu equipo y no datos dentro de tu software, eso ya existe en el portal y se explica en Active Panel-Calls.

Registra tu webhook de llamadas

Desde el portal

Ve a Configuración > Integraciones Privadas y abre la pestaña Webhooks. Pega tu dirección en el campo de Llamadas y guarda. Tu URL tiene que estar activa antes de guardar: la probamos, y si no responde con HTTP 200 el guardado se rechaza. Para dejar de recibir eventos, borra el campo y guarda de nuevo.

Desde la API

curl --request PUT \
  --url https://api.zonitel.com/api/v3/integrations/calls/webhooks \
  --header 'Authorization: Bearer TU_TOKEN' \
  --header 'X-Client-Id: TU_CLIENT_ID' \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://tusitio.com/webhook/llamadas"}'

La misma ruta responde a GET, que devuelve la dirección registrada actualmente, y a DELETE, que la elimina.

Qué tiene que hacer tu servidor

• Responder HTTP 200 en menos de cinco segundos. Confirma primero el evento y procesa después en una cola.
• Tolerar repeticiones. Usa el identificador de la llamada como clave e ignora un evento que ya guardaste.
• Estar accesible por HTTPS en una dirección pública.

Los campos que recibes y las respuestas de error que esperamos están detallados en Incoming Call Webhooks. Si quieres ver uno llegar, apunta el webhook a una URL que registre peticiones durante unos minutos y haz una llamada de prueba.

Descarga el historial de llamadas

El historial viene paginado y filtrado por fecha. El formato de fecha es AAAA-MM-DD HH:MM:SS.

curl --get \
  --url 'https://api.zonitel.com/api/v3/integrations/calls' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=25' \
  --data-urlencode 'fromDate=2026-08-01 00:00:00' \
  --data-urlencode 'toDate=2026-08-20 23:59:59' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'Accept: application/json'

Codifica como URL las fechas que contienen espacios. La respuesta del historial incluye totalItemCount, currentPage, itemNumberPerPage e items. Guarda el xmlCdrUuid de cada fila para las consultas posteriores. Puedes filtrar por direction, status, extensionUuid y recording; consulta los valores admitidos en la referencia API.

Un patrón de sincronización que resiste una caída

• En la primera conexión, recorre las páginas desde la fecha que elijas hasta que una venga incompleta. Sube limit para avanzar más rápido y mantén cada ventana en un periodo que puedas reintentar sin coste.
• Después de esa carga inicial, deja que el webhook lleve el tráfico del día a día.
• Una vez por noche, vuelve a pedir las últimas veinticuatro o cuarenta y ocho horas y descarta lo que ya tengas. Ese solapamiento casi no cuesta nada y cierra cualquier hueco que haya dejado un webhook que tu servidor rechazó.
• Guarda el identificador de cada llamada. Las grabaciones y las transcripciones se piden con él, y es lo que hace posible descartar duplicados.

Obtén una grabación o una transcripción

Ambas se piden con el identificador de la llamada, que en la API se llama xmlCdrUuid. Lo obtienes de un evento del webhook o de una fila del historial.

curl --request GET \
  --url https://api.zonitel.com/api/v3/integrations/calls/UUID_LLAMADA/stream \
  --header 'Authorization: Bearer TU_TOKEN' \
  --header 'X-Client-Id: TU_CLIENT_ID' \
  --output llamada.wav

El endpoint de transcripción devuelve un objeto JSON con el texto y su estado de procesamiento.

curl --request GET \
  --url https://api.zonitel.com/api/v3/integrations/calls/UUID_LLAMADA/transcription \
  --header 'Authorization: Bearer TU_TOKEN' \
  --header 'X-Client-Id: TU_CLIENT_ID' \
  --header 'Accept: application/json'

Comprueba status e isReady antes de utilizar la transcripción. Una llamada que todavía se procesa puede devolver HTTP 200 con status: "processing" y una lista segments vacía. Cuando esté lista, utiliza text, textWithRoles o los segments estructurados con role, content, beginOffsetMillis y endOffsetMillis.

HTTP 403 indica que la transcripción no está habilitada en la cuenta. Al activarla se aplica a las llamadas desde ese momento; no crea transcripciones de llamadas anteriores. HTTP 404 puede indicar que no se encontró la llamada o que no tiene transcripción.

Las dos dependen de que la llamada se haya capturado. El audio existe solo para las extensiones configuradas para grabar, y la transcripción solo donde está activada en tu cuenta, algo que se explica en Call Transcription Insights. Espera que la transcripción aparezca un rato después de terminar la llamada, no al instante.

Lanza una llamada desde tu aplicación

Es la base de un botón de clic para llamar en un CRM. La petición genera una llamada entre una de tus extensiones y un destino, que puede ser un número externo u otra extensión.

curl --request POST \
  --url https://api.zonitel.com/api/v3/integrations/calls/initiate \
  --header 'Authorization: Bearer TU_TOKEN' \
  --header 'X-Client-Id: TU_CLIENT_ID' \
  --header 'Content-Type: application/json' \
  --data '{"originExtension": "101", "destinationNumber": "13055550123", "destinationName": "Acme Dental"}'

originExtension es la extensión que hace la llamada, destinationNumber es el número o la extensión a la que se llama, y destinationName es la etiqueta que la acompaña. Si pones un número de extensión en destinationNumber, tienes una llamada interna.

Consultas de apoyo

Tres endpoints de solo lectura te ayudan a relacionar tus registros con los nuestros: /integrations/extensions lista las extensiones de tu cuenta, /integrations/extensions/report devuelve un resumen de ellas y /integrations/numbers lista tus números de teléfono. Pídelos una vez, guárdalos en caché y actualízalos cuando cambie tu cuenta.

Buenas prácticas

• Emite una credencial distinta para cada sistema que conectes. Así, cuando haya que revocar una, desactivas una sola integración y no todas.
• Mantén los tokens fuera de los repositorios y del código del navegador. Si uno queda expuesto, revócalo desde la pestaña Credenciales y emite otro.
• Reintenta las peticiones fallidas con una espera creciente, no en un bucle cerrado.
• Registra el identificador de la llamada junto al identificador de tu propio registro. Todas las peticiones posteriores dependen de él.

La mensajería tiene su propia guía: Envía y recibe SMS con la API.

¿Necesitas ayuda?

Llamada/Texto/WhatsApp: (833) 966-4835
Email: info@zonitel.com