Introducción a la API

La API sirve para que tus sistemas hagan lo que hoy hace una persona al subir llamadas: enviar cada grabación a Caller en cuanto termina la llamada. El resultado del análisis vuelve a tus sistemas por un webhook.

Son dos piezas y no hay más:

No hay peticiones para leer llamadas, listar resultados o gestionar plantillas. Si necesitas los resultados en otro sistema, el camino es el webhook; para una descarga puntual, el CSV de la app.

1. Tu centralita envía la grabación con una clave de API. Caller responde enseguida con el identificador de la llamada:

   { "id": "k57e2xq9m4hc8w1t6b0z5y2e97c4n1ad", "status": "queued" }

2. Caller la transcribe y la analiza con la plantilla que le corresponde. Suele tardar unos minutos.

3. Caller envía el resultado a tu webhook: puntuación, criterios, tema, resumen y un enlace a la llamada.

• Dirección base: https://api.caller.ee/v1
• Autenticación: una clave en la cabecera Authorization: Bearer ck_….
• Petición: multipart/form-data, como un formulario con un archivo.
• Respuesta: JSON en UTF-8, tanto si va bien como si no.
• Conexión: siempre HTTPS.

Crea una clave en Integraciones → API → Crear una clave, guárdala en una variable de entorno y envía una grabación:

export CALLER_API_KEY="ck_…"   # la clave que acabas de crear

curl https://api.caller.ee/v1/calls \
  -H "Authorization: Bearer $CALLER_API_KEY" \
  -F "file=@AG1143_Lucia_Romero_2026-10-09_10-42-11_611284.mp3"

La llamada aparece al momento en Llamadas, en la vista En proceso.

Tres cosas que evitan sorpresas el primer día:

• Ten al menos una plantilla. Sin plantilla las llamadas se transcriben pero no se analizan, y el webhook solo se envía cuando una llamada queda analizada.
• Da de alta a los agentes con su código en Equipo. Así cada grabación se archiva con su agente, la envíes con agent_code o lo lleve en el nombre del archivo.
• Envía siempre external_id. Es lo que permite reintentar una petición sin duplicar la llamada.

La versión va en la dirección (/v1). Dentro de una versión se pueden añadir campos nuevos a las respuestas y al cuerpo del webhook, pero los que existen no se renombran ni se quitan. Escribe tu integración de modo que ignore los campos que no conozca.