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.
Listar llamadas
Sección titulada «Listar llamadas»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 |
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 |
Una llamada con su transcripción
Sección titulada «Una llamada con su transcripción»GET /v1/calls/{call_id} devuelve los mismos campos y, además, transcript[]: la conversación turno a turno.
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.
Reglas de los datos
Sección titulada «Reglas de los datos»- Los días se cortan en tu zona horaria. El rango va de las 00:00 de
froma las 24:00 detoentimezone. - Las llamadas son las de tus agentes. Una llamada que no llegó a ningún agente (
dispositiondistinto deCONNECTEDy sinagent_id) no forma parte de la API: ni en la lista ni por id. - El cursor es de su consulta. Un
cursorsolo sirve con los mismos filtros y el mismolimitque la página que lo devolvió; con otros, la respuesta es 400invalid_query. Si cambias los filtros, empieza de nuevo sincursor. - 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_cursorseanull. - 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_idsfuera de ellos es 403insufficient_scope.
