Llamadas

La API de Llamadas te permite listar el historial de llamadas, ver detalles de llamadas con transcripciones, iniciar llamadas salientes y ejecutar campanas de llamadas por lotes.

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, voicemail, invalid_number, caller_hangup)
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.

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"
}

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.

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" }
  ]
}