Llamadas de Voz

Interacciones de voice bot con IA incluyendo IVR y campanas de salida.

Endpoints

MetodoEndpointAlcanceDescripcion
GET/api/v1/voice-callsvoice:readListar llamadas de voz con filtros
GET/api/v1/voice-calls/{id}voice:readObtener una llamada de voz con transcripcion completa
GET/api/v1/voice-calls/{id}/recording-urlaudio:downloadGenerar URL SAS de grabacion (expira en 15 min)
GET/api/v1/voice-calls/{id}/epa-resultsvoice:readObtener resultados de encuesta post-llamada
GET/api/v1/voice-calls/{callId}/contextvoice:readObtener el contexto de la llamada para el traspaso a ejecutivo (disponible durante la llamada)

Parametros de Consulta (Endpoint de Listado)

ParametroTipoDescripcion
campaignIdstringFiltrar por ID de campana
statestringFiltrar por estado de llamada (ej., Completed, Busy, NoAnswer)
directionstringFiltrar por direccion (Inbound o Outbound)
dateFromdatetimeInicio del rango de fechas
dateTodatetimeFin del rango de fechas
pageintNumero de pagina para paginacion
pageSizeintNumero de resultados por pagina

Objeto de Llamada de Voz

{
  "id": "vc_abc123",
  "campaignId": "camp_456",
  "direction": "Outbound",
  "state": "Completed",
  "startTime": "2024-01-15T10:30:00Z",
  "endTime": "2024-01-15T10:35:12Z",
  "durationSeconds": 312,
  "talkTimeSeconds": 287,
  "outcome": "Successful",
  "transcript": [
    { "role": "agent", "text": "Hello, this is...", "timestamp": "00:00:01" },
    { "role": "customer", "text": "Hi, yes...", "timestamp": "00:00:04" }
  ],
  "epaResults": {
    "state": "Completed",
    "completionReason": "AllAnswered",
    "totalQuestions": 3,
    "questionsAnswered": 3,
    "calculatedScore": 85.5,
    "responses": [
      { "question": "How satisfied are you?", "answer": "Very satisfied", "score": 5 }
    ]
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

Resultados EPA (Encuesta Post-Atencion)

Los resultados EPA (Encuesta Post-Atencion) estan disponibles cuando se configura una encuesta post-llamada para la campana. Usa el endpoint /epa-results o accede a ellos en linea a traves del objeto de llamada de voz.

CampoTipoDescripcion
statestringEstado de la encuesta (ej., Completed, Partial, NotStarted)
completionReasonstringRazon de finalizacion de la encuesta (ej., AllAnswered, HangUp, Timeout)
totalQuestionsintNumero total de preguntas de la encuesta
questionsAnsweredintNumero de preguntas respondidas por el llamante
calculatedScorenumberPuntaje de satisfaccion agregado
responsesarrayEntradas individuales de pregunta/respuesta/puntaje

Flujo de Descarga de Grabaciones

Las grabaciones de audio se acceden mediante URLs firmadas temporales. Sigue este proceso de tres pasos:

# 1. Get voice call list
GET /api/v1/voice-calls?state=Completed&direction=Outbound
Authorization: Bearer <token>

# 2. Request a recording SAS URL (valid for 15 minutes)
GET /api/v1/voice-calls/vc_abc123/recording-url
Authorization: Bearer <token>

Response:
{
  "recordingUrl": "https://storage.blob.core.windows.net/recordings/vc_abc123.wav?sv=...&se=...",
  "expiresAt": "2024-01-15T10:45:00Z"
}

# 3. Download the recording (no auth required, URL is pre-signed)
GET https://storage.blob.core.windows.net/recordings/vc_abc123.wav?sv=...&se=...

Contexto de la Llamada (Traspaso a Ejecutivo)

Cuando el voice bot traspasa una llamada a un ejecutivo, publica un documento de contexto de esa llamada para que el ejecutivo vea quien llama y que ya se resolvio. Consultalo con el valor del header SIP X-Auralytik-Call-Id que viaja en la pierna transferida: ese valor es el segmento {callId} de la ruta, no el ID del registro de la llamada.

La parte estructurada — cliente, datos capturados y acciones — se escribe antes de que se complete la transferencia, por lo que ya esta disponible en el momento en que se abre la pantalla del ejecutivo. La narrativa de IA es best-effort y puede llegar algunos cientos de milisegundos despues: ramifica segun status y muestra los campos estructurados de inmediato en vez de bloquear la pantalla esperando el resumen.

CampoTipoDescripcion
callIdstringEl valor de X-Auralytik-Call-Id al que corresponde este contexto
statusstringready cuando el resumen de IA esta presente, partial cuando aun no lo esta
campaignIdstringCampana a la que pertenece la llamada
directionstringInbound u Outbound
startedAtdatetimeInicio de la llamada (UTC)
transferRequestedAtdatetimeMomento en que se solicito la transferencia (UTC)
transferDestinationstringEl anexo o numero marcado para la transferencia
transferReasonstringMotivo por el que el bot traspaso la llamada
customerobjectid, name, phone, authenticated, authMethod, authenticatedAt. phone viene en E.164 cuando el numero es inequivocamente nacional; anexos y codigos cortos pasan tal como se marcaron. Los campos sin valor vienen ausentes, no null
capturedobjectMapa plano de los datos recogidos durante la llamada, con los nombres de clave del propio flujo
factsarrayHechos recogidos con procedencia: key, value, provenance, source, recordedAt
actionsarrayAcciones de backend ejecutadas por el bot: functionName, success, executedAt
summarystringNarrativa de IA de la llamada hasta ese momento. Viene ausente del cuerpo (no null) mientras esta pendiente
summaryStatusstringready, pending, failed o disabled

Cada entrada de facts trae una provenance: system (definida por la plataforma, como la campana o el tema atendido), verified (confirmada por autenticacion o por una consulta a backend) o asserted (declarada por el cliente y no verificada). Usala para decidir sobre que puede actuar el ejecutivo sin volver a preguntar.

Agrega ?wait=1500 para esperar brevemente a que termine el resumen. El valor va en milisegundos y se acota a 0–3000; la peticion retorna apenas el resumen esta listo, asi que la espera es un tope y no un retardo. El contexto es una pantalla de atencion, no un archivo: trae el resumen y los campos estructurados, no los turnos de la conversacion. La transcripcion completa queda disponible despues de la llamada en /api/v1/voice-calls/{id}, con el mismo identificador. Una llamada sin contexto publicado devuelve 404: la misma respuesta para un ID desconocido, la llamada de otro tenant o un contexto ya expirado. Los contextos se conservan alrededor de una hora.

# Aparece la pantalla del ejecutivo. Busca la llamada por su valor X-Auralytik-Call-Id.
GET /api/v1/voice-calls/8f3c1a20-5d6e-4b71-9c02-7a1e5f8d4b33/context?wait=1500
Authorization: Bearer <token>

Response:
{
  "callId": "8f3c1a20-5d6e-4b71-9c02-7a1e5f8d4b33",
  "status": "ready",
  "campaignId": "camp_456",
  "direction": "Inbound",
  "startedAt": "2024-01-15T10:30:00Z",
  "transferRequestedAt": "2024-01-15T10:33:41Z",
  "transferDestination": "9010",
  "transferReason": "El cliente pidio hablar con un ejecutivo",
  "customer": {
    "name": "Maria Rojas",
    "phone": "+56912345678",
    "authenticated": true,
    "authMethod": "IdentityDocument",
    "authenticatedAt": "2024-01-15T10:30:52Z"
  },
  "captured": {
    "TIPO_CONTACTO": "titular",
    "MONTO_SOLICITADO": "120000"
  },
  "facts": [
    { "key": "customer_name", "value": "Maria Rojas", "provenance": "verified",
      "source": "authentication", "recordedAt": "2024-01-15T10:30:52Z" }
  ],
  "actions": [
    { "functionName": "consultar_saldo", "success": true, "executedAt": "2024-01-15T10:31:20Z" }
  ],
  "summary": "Titular verificado. Consulto por un saldo pendiente y pidio hablar con un ejecutivo.",
  "summaryStatus": "ready"
}

Documentacion completa de llamadas de voz proximamente

Esquemas detallados de transcripciones, eventos de webhook para cambios de estado de llamadas y capacidades de exportacion masiva estan siendo documentados.

Solicitar Acceso API