Llamadas de Voz
Interacciones de voice bot con IA incluyendo IVR y campanas de salida.
Endpoints
| Metodo | Endpoint | Alcance | Descripcion |
|---|---|---|---|
| GET | /api/v1/voice-calls | voice:read | Listar llamadas de voz con filtros |
| GET | /api/v1/voice-calls/{id} | voice:read | Obtener una llamada de voz con transcripcion completa |
| GET | /api/v1/voice-calls/{id}/recording-url | audio:download | Generar URL SAS de grabacion (expira en 15 min) |
| GET | /api/v1/voice-calls/{id}/epa-results | voice:read | Obtener resultados de encuesta post-llamada |
| GET | /api/v1/voice-calls/{callId}/context | voice:read | Obtener el contexto de la llamada para el traspaso a ejecutivo (disponible durante la llamada) |
Parametros de Consulta (Endpoint de Listado)
| Parametro | Tipo | Descripcion |
|---|---|---|
| campaignId | string | Filtrar por ID de campana |
| state | string | Filtrar por estado de llamada (ej., Completed, Busy, NoAnswer) |
| direction | string | Filtrar por direccion (Inbound o Outbound) |
| dateFrom | datetime | Inicio del rango de fechas |
| dateTo | datetime | Fin del rango de fechas |
| page | int | Numero de pagina para paginacion |
| pageSize | int | Numero 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.
| Campo | Tipo | Descripcion |
|---|---|---|
| state | string | Estado de la encuesta (ej., Completed, Partial, NotStarted) |
| completionReason | string | Razon de finalizacion de la encuesta (ej., AllAnswered, HangUp, Timeout) |
| totalQuestions | int | Numero total de preguntas de la encuesta |
| questionsAnswered | int | Numero de preguntas respondidas por el llamante |
| calculatedScore | number | Puntaje de satisfaccion agregado |
| responses | array | Entradas 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.
| Campo | Tipo | Descripcion |
|---|---|---|
| callId | string | El valor de X-Auralytik-Call-Id al que corresponde este contexto |
| status | string | ready cuando el resumen de IA esta presente, partial cuando aun no lo esta |
| campaignId | string | Campana a la que pertenece la llamada |
| direction | string | Inbound u Outbound |
| startedAt | datetime | Inicio de la llamada (UTC) |
| transferRequestedAt | datetime | Momento en que se solicito la transferencia (UTC) |
| transferDestination | string | El anexo o numero marcado para la transferencia |
| transferReason | string | Motivo por el que el bot traspaso la llamada |
| customer | object | id, 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 |
| captured | object | Mapa plano de los datos recogidos durante la llamada, con los nombres de clave del propio flujo |
| facts | array | Hechos recogidos con procedencia: key, value, provenance, source, recordedAt |
| actions | array | Acciones de backend ejecutadas por el bot: functionName, success, executedAt |
| summary | string | Narrativa de IA de la llamada hasta ese momento. Viene ausente del cuerpo (no null) mientras esta pendiente |
| summaryStatus | string | ready, 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