Ir al contenido

Chats

Las conversaciones de WhatsApp de tus agentes, con sus mensajes: parámetros, paginación y qué devuelve cada endpoint.

Los endpoints de chats devuelven las conversaciones de WhatsApp que han mantenido tus agentes: quién escribió, desde qué número de empresa, cómo terminó la conversación y, en el detalle, sus mensajes. Necesitan el permiso chats:read.

Endpoint Ruta Permiso
Listar chats GET /v1/chats chats:read
Un chat con sus mensajes GET /v1/chats/{chat_id} chats:read

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

GET /v1/chats devuelve las conversaciones iniciadas en un rango de días, de la más reciente a la más antigua, sin sus mensajes.

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 los chats de los agentes de esos locales
agent_ids texto, repetible todos tus agentes 100 como máximo; solo los chats de esos agentes
limit de 1 a 100 50 Chats 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/chats?from=2026-10-01&to=2026-10-31&timezone=Europe/Madrid"
# repite con &cursor=<meta.next_cursor> hasta que next_cursor sea null
{
"data": [
{
"id": "…",
"agent_id": "…",
"channel": "whatsapp",
"contact_phone": "+34600111222",
"business_phone": "+34910000000",
"started_at": "2026-10-31T18:42:10Z",
"ended_at": "2026-10-31T18:55:02Z",
"status": "FINISHED",
"finish_reason": "Expired."
}
],
"meta": { "limit": 50, "next_cursor": "…" }
}
Campo Qué es
id El identificador del chat; pásalo a GET /v1/chats/{chat_id}
agent_id El agente que mantuvo la conversación; null si ese agente ya no es tuyo
channel Hoy siempre whatsapp
contact_phone El número de WhatsApp del contacto, en E.164
business_phone El número de WhatsApp de empresa al que escribió el contacto o desde el que se le escribió, en E.164
started_at Cuándo empezó la conversación (UTC)
ended_at Cuándo terminó; null mientras sigue abierta
status IN_PROGRESS o FINISHED
finish_reason Por qué terminó, p. ej. Hangup, Expired., No actions., Template button; pueden aparecer otros. null mientras sigue abierta

GET /v1/chats/{chat_id} devuelve los mismos campos más messages[], del más antiguo al más reciente, y messages_truncated.

Ventana de terminal
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/chats/<chat_id>"
Campo Qué es
messages[].id El identificador del mensaje
messages[].role user (el contacto) o agent
messages[].type El tipo de mensaje tal como lo llama WhatsApp: text, image, audio, video, document, location, template, interactive, button, reaction…; null si no se puede leer
messages[].text Lo que dice: su texto, el pie de un archivo, el cuerpo de un mensaje interactivo o la opción que eligió el contacto; null si no tiene
messages[].sent_at Cuándo se envió o se recibió
messages[].status created, sent, delivered, read, failed, deleted o warning
messages_truncated true si la conversación tiene más de los 200 mensajes devueltos

Un chat que no es de tu cliente, o que no existe, es 404 not_found.

  • Solo texto. Los archivos (imágenes, audios, documentos), los parámetros de las plantillas y los precios no forman parte de la API: un mensaje con un archivo llega con su type y su pie, si tiene.
  • El rango es sobre cuándo empezó el chat, cortado en tu zona horaria. Una conversación que empezó antes de tu última sincronización puede seguir abierta: sincroniza con algo de solapamiento y quédate con uno por id.
  • Los chats son del propietario del agente cuando empezaron. Si un agente pasa a otra cuenta de Bookline, sus chats anteriores se quedan con el propietario anterior, con agent_id null; el nuevo propietario solo lee los que empezaron desde el cambio.
  • Solo los chats de tus agentes. Las conversaciones que gestionan los flujos compartidos de Bookline, y no uno de tus agentes, todavía no están en la API. Instagram tampoco es todavía un chat.
  • Paginar hasta hoy es seguro. Los chats que empiezan mientras paginas nunca repiten ni desplazan una fila. Para cuando next_cursor sea null.
  • Claves limitadas a algunos locales. La clave lista solo los chats de los agentes de esos locales, y un venue_ids fuera de ellos da 403 insufficient_scope.