Skip to content

Chats

The WhatsApp conversations your agents held, with their messages: parameters, paging and what each endpoint returns.

The chats endpoints return the WhatsApp conversations your agents held: who wrote, from which business number, how the conversation ended and, in the detail, its messages. They need the chats:read scope.

Endpoint Route Scope
List chats GET /v1/chats chats:read
One chat with its messages GET /v1/chats/{chat_id} chats:read

In the examples, $BASE is https://api.bookline.ai/v1 and $BOOKLINE_API_KEY is your key, as in the quick start.

GET /v1/chats returns the conversations started in a window of days, newest first, without their messages.

Parameter Type Default Rules
from date YYYY-MM-DD required First day of the window, inclusive, in timezone
to date YYYY-MM-DD required Last day, inclusive; not before from; at most 31 days
timezone IANA name UTC e.g. Europe/Madrid; days start and end in that zone
venue_ids UUID, repeatable all your venues At most 100; only the chats of those venues’ agents
agent_ids string, repeatable all your agents At most 100; only the chats of those agents
limit 1 to 100 50 Chats per page
cursor string none meta.next_cursor of the previous page, with the same filters and the same limit
customer_id UUID the key’s customer See what each key reads
Ventana de terminal
curl -s -H "apikey: $BOOKLINE_API_KEY" \
"$BASE/chats?from=2026-10-01&to=2026-10-31&timezone=Europe/Madrid"
# repeat with &cursor=<meta.next_cursor> until next_cursor is 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": "…" }
}
Field What it is
id The chat’s identifier; pass it to GET /v1/chats/{chat_id}
agent_id The agent that held the conversation; null when that agent is no longer yours
channel Always whatsapp today
contact_phone The contact’s WhatsApp number, E.164
business_phone The business WhatsApp number the contact wrote to or was written from, E.164
started_at When the conversation started (UTC)
ended_at When it ended; null while it is open
status IN_PROGRESS or FINISHED
finish_reason Why it ended, e.g. Hangup, Expired., No actions., Template button; others may appear. null while open

GET /v1/chats/{chat_id} returns the same fields plus messages[], oldest first, and messages_truncated.

Ventana de terminal
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/chats/<chat_id>"
Field What it is
messages[].id The message’s identifier
messages[].role user (the contact) or agent
messages[].type The kind of message as WhatsApp names it: text, image, audio, video, document, location, template, interactive, button, reaction…; null when unreadable
messages[].text What it says: its text, a media caption, the body of an interactive message or the option the contact picked; null when it has none
messages[].sent_at When it was sent or received
messages[].status created, sent, delivered, read, failed, deleted or warning
messages_truncated true when the conversation has more than the 200 messages returned

A chat that is not your customer’s, or that does not exist, is 404 not_found.

  • Text only. Media (images, audio, files), template parameters and prices are not part of the API: a media message comes with its type and its caption, if any.
  • The window is on when the chat started, cut in your timezone. A conversation that started before your last sync can still be going on: sync with some overlap and keep one per id.
  • Chats belong to the agent’s owner when they started. If an agent moves to another Bookline account, its earlier chats stay with the previous owner, with agent_id null; the new owner reads only those started since the move.
  • Only your agents’ chats. Conversations held by Bookline’s own shared flows rather than by one of your agents are not in the API yet. Instagram is not a chat yet either.
  • Paging up to today is safe. Chats that start while you page never repeat or shift a row. Stop when next_cursor is null.
  • Venue-restricted keys. The key lists only the chats of those venues’ agents, and a venue_ids outside them is 403 insufficient_scope.