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.
List chats
Section titled “List chats”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 |
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 |
One chat with its messages
Section titled “One chat with its messages”GET /v1/chats/{chat_id} returns the same fields plus messages[], oldest first, and messages_truncated.
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.
Data rules
Section titled “Data rules”- Text only. Media (images, audio, files), template parameters and prices are not part of the API: a media message comes with its
typeand 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_idnull; 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_cursorisnull. - Venue-restricted keys. The key lists only the chats of those venues’ agents, and a
venue_idsoutside them is 403insufficient_scope.
Related
Section titled “Related”- Calls: the phone calls your agents answer.
- Contacts: the people who reached you.
- Errors and rate limits.
