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.
Listar chats
Sección titulada «Listar chats»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 |
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 |
Un chat con sus mensajes
Sección titulada «Un chat con sus mensajes»GET /v1/chats/{chat_id} devuelve los mismos campos más messages[], del más antiguo al más reciente, y messages_truncated.
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.
Reglas de los datos
Sección titulada «Reglas de los datos»- 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
typey 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_idnull; 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_cursorseanull. - Claves limitadas a algunos locales. La clave lista solo los chats de los agentes de esos locales, y un
venue_idsfuera de ellos da 403insufficient_scope.
Relacionado
Sección titulada «Relacionado»- Llamadas: las llamadas telefónicas que atienden tus agentes.
- Contactos: las personas que han contactado contigo.
- Errores y límites de uso.
