Ir al contenido

Llamadas

Las llamadas que atienden tus agentes, con su transcripción: parámetros, paginación y qué devuelve cada endpoint.

Los endpoints de llamadas devuelven las llamadas telefónicas que han atendido tus agentes: quién llamó, a qué número, cómo terminó la llamada y, en el detalle, la conversación turno a turno. Necesitan el permiso calls:read.

Endpoint Ruta Permiso
Listar llamadas GET /v1/calls calls:read
Una llamada con su transcripción GET /v1/calls/{call_id} calls:read

En los ejemplos, $BASE es https://api.bookline.ai/v1 y $BOOKLINE_API_KEY tu clave, como en los primeros pasos.

GET /v1/calls devuelve las llamadas atendidas por tus agentes en un rango de días, de la más reciente a la más antigua, sin transcripción.

Parámetro Tipo Por defecto Reglas
from fecha YYYY-MM-DD obligatorio Primer día del rango, incluido, en timezone
to fecha YYYY-MM-DD obligatorio Último día, incluido; no puede ser anterior a from; 31 días como máximo
timezone nombre IANA UTC p. ej. Europe/Madrid; los días empiezan y terminan en esa zona
venue_ids UUID, repetible todos tus locales 100 como máximo; solo las llamadas de los agentes de esos locales (ids de GET /venues)
agent_ids texto, repetible todos tus agentes 100 como máximo; solo las llamadas de esos agentes
limit de 1 a 100 50 Llamadas por página
cursor texto ninguno meta.next_cursor de la página anterior, con los mismos filtros y el mismo limit
customer_id UUID el cliente de la clave Consulta qué lee cada clave
Ventana de terminal
curl -s -H "apikey: $BOOKLINE_API_KEY" \
"$BASE/calls?from=2026-10-01&to=2026-10-31&timezone=Europe/Madrid&limit=50"
# repite con &cursor=<meta.next_cursor> hasta que next_cursor sea null
{
"data": [
{
"id": "…",
"started_at": "2026-10-31T18:42:10Z",
"caller_number": "+34600111222",
"called_number": "+34910000000",
"disposition": "CONNECTED",
"agent_id": "…",
"tags": []
}
],
"meta": { "limit": 50, "next_cursor": "…" }
}
Campo Qué es
id Identificador de la llamada; úsalo en GET /v1/calls/{call_id}
started_at Cuándo empezó la llamada (UTC)
caller_number Número que llamó
called_number Número al que llamó
disposition Cómo terminó. Hoy siempre CONNECTED: solo se sirven las llamadas que atendió un agente
agent_id Agente que la atendió. Hoy siempre presente
tags Etiquetas de la llamada

GET /v1/calls/{call_id} devuelve los mismos campos y, además, transcript[]: la conversación turno a turno.

Ventana de terminal
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/calls/<call_id>"
{
"id": "…",
"started_at": "2026-10-31T18:42:10Z",
"caller_number": "+34600111222",
"called_number": "+34910000000",
"disposition": "CONNECTED",
"agent_id": "…",
"tags": [],
"transcript": [
{
"at": "2026-10-31T18:42:12Z",
"caller_said": "Una mesa para dos esta noche",
"agent_said": ["Claro, ¿a qué hora os gustaría venir?"]
}
]
}
Campo Qué es
transcript[].at Cuándo empezó el turno
transcript[].caller_said Lo que dijo quien llamaba, o los dígitos que pulsó; null si no dijo nada
transcript[].agent_said Lo que respondió el agente, en orden

Una llamada que no es de tu cliente, o que no existe, es 404 not_found.

  • Los días se cortan en tu zona horaria. El rango va de las 00:00 de from a las 24:00 de to en timezone.
  • Las llamadas son las de tus agentes. Una llamada que no llegó a ningún agente (disposition distinto de CONNECTED y sin agent_id) no forma parte de la API: ni en la lista ni por id.
  • El cursor es de su consulta. Un cursor solo sirve con los mismos filtros y el mismo limit que la página que lo devolvió; con otros, la respuesta es 400 invalid_query. Si cambias los filtros, empieza de nuevo sin cursor.
  • Paginar hasta hoy es seguro. Cada página continúa justo después de la última llamada de la anterior, así que las llamadas que entran mientras recorres las páginas no repiten ni desplazan ninguna fila. Para cuando next_cursor sea null.
  • Al sincronizar, solapa la ventana. Una llamada aparece cuando termina, con la hora a la que empezó: una llamada larga que empezó antes de tu última sincronización puede aparecer después. Si sincronizas cada día, pide también el día anterior y quédate con una por id.
  • Claves limitadas a locales. Si tu acceso en el portal está limitado a ciertos locales, la clave solo lista las llamadas de los agentes de esos locales, y un venue_ids fuera de ellos es 403 insufficient_scope.