Llamadas
La API de Llamadas te permite listar el historial de llamadas, ver detalles de llamadas con transcripciones, descargar grabaciones, iniciar llamadas salientes y ejecutar campanas de llamadas por lotes.
Cada endpoint de esta seccion acepta ambos metodos de autenticacion: JWT Bearer y clave de API (X-API-Key). Esto significa que una integracion automatizada (por ejemplo, un manejador que recibe el webhook de fin de llamada) puede listar llamadas y descargar grabaciones usando solo una clave de API.
Listar Llamadas
GET /calls
Devuelve una lista paginada de registros de llamadas, ordenados por hora de inicio (mas recientes primero).
Parametros de Consulta
| Parametro | Tipo | Por defecto | Descripcion |
|---|---|---|---|
page | integer | 1 | Numero de pagina |
page_size | integer | 20 | Elementos por pagina (maximo 100) |
direction | string | -- | Filtrar por inbound o outbound |
status | string | -- | Filtrar por estado de llamada (ej. completed, failed) o resultado (ej. voicemail, caller_hangup) |
search | string | -- | Buscar por numero de telefono (origen o destino) |
Respuesta
{
"items": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"call_sid": "CA1234567890abcdef",
"direction": "inbound",
"from_number": "+15551234567",
"to_number": "+15559876543",
"start_time": "2026-03-01T14:30:00Z",
"end_time": "2026-03-01T14:32:45Z",
"duration": 165.0,
"status": "completed",
"outcome": "completed",
"error_reason": null,
"created_at": "2026-03-01T14:30:00Z",
"agent_name": "Support Agent"
}
],
"total": 142,
"page": 1,
"page_size": 20
}
Campos del Registro de Llamada
| Campo | Tipo | Descripcion |
|---|---|---|
id | uuid | ID interno del registro de llamada |
call_sid | string | Twilio Call SID |
direction | string | inbound o outbound |
from_number | string | Numero de telefono del llamante |
to_number | string | Numero de telefono llamado |
start_time | datetime | Marca de tiempo de inicio de llamada |
end_time | datetime | null | Marca de tiempo de fin de llamada |
duration | float | null | Duracion de la llamada en segundos |
status | string | Estado de la llamada (completed, failed, in-progress, queued) |
outcome | string | null | Resultado de la llamada (completed, caller_hangup, no_answer, timeout, transferred, voicemail, invalid_number, failed). timeout indica que la llamada terminó por un límite de silencio o de duración máxima; caller_hangup es una desconexión real del llamante. |
error_reason | string | null | Descripcion del error si la llamada fallo |
created_at | datetime | Marca de tiempo de creacion del registro |
agent_name | string | null | Nombre del agente que atendio la llamada |
Obtener Detalle de Llamada
GET /calls/{call_id}
Devuelve una llamada individual con detalles completos incluyendo la transcripcion de la conversacion y metricas de uso de proveedores.
Respuesta
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"call_sid": "CA1234567890abcdef",
"direction": "inbound",
"from_number": "+15551234567",
"to_number": "+15559876543",
"start_time": "2026-03-01T14:30:00Z",
"end_time": "2026-03-01T14:32:45Z",
"duration": 165.0,
"status": "completed",
"outcome": "completed",
"error_reason": null,
"created_at": "2026-03-01T14:30:00Z",
"agent_name": "Support Agent",
"transcript": [
{ "role": "user", "content": "Hi, I need help with my order." },
{ "role": "assistant", "content": "Of course! Could you share your order number?" }
],
"provider_usage": {
"deepgram": { "type": "stt", "model": "nova-2" },
"openai": { "type": "llm", "model": "gpt-4o" },
"elevenlabs": { "type": "tts", "model": "eleven_turbo_v2" }
},
"recording_url": "call-CA1234567890abcdef.wav"
}
Campos Adicionales de Detalle
| Campo | Tipo | Descripcion |
|---|---|---|
transcript | array | null | Turnos de conversacion con role y content |
provider_usage | object | null | Nombres de proveedores y modelos utilizados durante la llamada |
recording_url | string | null | Nombre del archivo de grabacion WAV (si la grabacion estaba habilitada) |
Descargar Grabacion
GET /calls/{call_id}/recording
Descarga el archivo de grabacion WAV de una llamada. Devuelve 404 si no hay grabacion disponible.
El webhook call.completed incluye un recording_download_url que apunta a este endpoint. Descargalo con tu clave de API en la cabecera X-API-Key para obtener el audio.
Respuesta
200 OK con Content-Type: audio/wav y el contenido binario del archivo.
Iniciar Llamada Saliente
POST /calls
Encola una llamada saliente individual. La llamada se procesa de forma asincrona a 1 llamada por segundo por un worker en segundo plano. La respuesta se devuelve inmediatamente con un call_id y un call_sid provisional que se actualiza cuando Twilio asigna el SID real.
Este endpoint acepta autenticacion tanto por Bearer JWT como por API key.
Cuerpo de la Solicitud
{
"to_number": "+15551234567",
"from_number": "+15559876543",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"variables": {
"customer_name": "Jane Doe",
"company_name": "Globex"
}
}
Campos de la Solicitud
| Campo | Tipo | Requerido | Descripcion |
|---|---|---|---|
to_number | string | Si | Numero de telefono de destino en formato E.164 |
from_number | string | No | Numero de identificacion del llamante. Si se omite, se resuelve desde el numero asignado al agente o el valor predeterminado de la configuracion SIP. |
agent_id | string | No | UUID del agente que manejara la llamada. Si se omite, se usa el agente asignado a from_number. |
variables | object | No | Sustituciones por llamada para las variables personalizadas del agente objetivo, como un mapa de nombre de variable a valor de texto. Se aplica solo a esta llamada y nunca cambia los valores predeterminados guardados del agente. Cada clave debe ser una variable personalizada definida en el agente objetivo; el nombre de una variable integrada o una clave desconocida devuelve 422 con las claves ofensivas. |
A diferencia del editor del panel, que solo advierte sobre marcadores no reconocidos y aun así te deja guardar, este endpoint valida variables de forma estricta. Una clave que coincide con el nombre de una variable integrada (las integradas nunca son sustituibles) o que no es una variable personalizada definida en el agente objetivo se rechaza con 422, y la respuesta lista las claves ofensivas. Esto expone los errores de integración de forma explícita en lugar de descartar datos silenciosamente. Consulta Variables Dinámicas para el modelo de variables.
Respuesta
202 Accepted
{
"call_id": "550e8400-e29b-41d4-a716-446655440000",
"call_sid": "queued-550e8400e29b",
"status": "queued"
}
El call_sid sera un valor provisional con prefijo queued- hasta que el worker en segundo plano inicie la llamada con Twilio.
Llamadas Salientes por Lotes
POST /calls/batch
Encola multiples llamadas salientes a la vez. Todas las llamadas comparten el mismo from_number y agent_id, y se procesan a 1 llamada por segundo.
Cuerpo de la Solicitud
{
"to_numbers": ["+15551111111", "+15552222222", "+15553333333"],
"from_number": "+15559876543",
"agent_id": "550e8400-e29b-41d4-a716-446655440000"
}
Campos de la Solicitud
| Campo | Tipo | Requerido | Descripcion |
|---|---|---|---|
to_numbers | array[string] | Si | Lista de numeros de telefono de destino |
from_number | string | No | Identificacion de llamante compartida para todas las llamadas |
agent_id | string | No | Agente que manejara todas las llamadas del lote |
Respuesta
202 Accepted
{
"batch_id": "batch-abc123",
"total": 3,
"status": "queued"
}
Obtener Estado del Lote
GET /calls/batch/{batch_id}
Consulta el progreso de un trabajo de llamadas por lotes.
Respuesta
{
"batch_id": "batch-abc123",
"total": 3,
"queued": 1,
"initiated": 1,
"failed": 1,
"calls": [
{ "to_number": "+15551111111", "status": "initiated", "call_sid": "CA..." },
{ "to_number": "+15552222222", "status": "queued", "call_sid": null },
{ "to_number": "+15553333333", "status": "failed", "call_sid": null, "error": "Invalid number" }
]
}