Docs
BetaThe V4 API is in beta — endpoints and functionality may change.
Contactsv4

Get contact timeline

GET/contacts/{contactId}/timeline

A single, chronological cross-channel activity feed for a contact, unifying every conversation the contact takes part in — both 1:1 chats keyed on the contact's identities and group chats where the contact is a current member — across all channel types. After a merge, the survivor's timeline includes the absorbed contact's history automatically. Each entry is a polymorphic envelope tagged by type; ordered newest-first by occurred_at. By default only message entries are returned; pass include_events=true to interleave lifecycle and chat events.

Path parameters

contactIdRequiredstring

Unique identifier of the contact, prefixed with ct_. Returned when you create a contact or by the List contacts endpoint.

Headers

AuthorizationRequiredstring

Your API key, sent as a bearer token: Authorization: Bearer <api_key>. Editing this stays in sync with the API key box on the right.

Bearer

Query parameters

limitoptionalinteger

Maximum number of items to return per page. Must be between 1 and 200; defaults to 50. Combine with cursor to paginate.

cursoroptionalstring

Opaque pagination cursor. Pass the next_cursor value from a previous response to fetch the next page; omit it on the first request.

include_eventsoptionalboolean

When true, interleaves non-message activity (delivery/read receipts, reactions, chat/group/typing changes) from the events ledger into the feed as message_event / chat_event entries. Defaults to false (messages only).

Returns

dataoptionalTimelineItem[]

Array of TimelineItem

typeoptionalstring

message: a message the contact sent or received. message_event: a lifecycle event for a message (sent/delivered/read/failed/reaction). chat_event: any other chat/group/typing event. Event entries only appear when include_events=true.

"message""message_event""chat_event"
occurred_atoptionalinteger

Epoch-millisecond timestamp the entry occurred at; the feed is ordered by this descending.

idoptionalstring

The underlying object id — a msg_ message id for message entries, an evt_ event id otherwise. Also the pagination sort key within a given occurred_at.

chat_idoptionalstring | null
channel_idoptionalstring | null
channel_typeoptionalstring | null

The channel type this entry occurred on. Always set for message entries; may be null for channel-agnostic events.

objectoptionalobject

The full entry payload. For message entries: id, chat_id, channel_id, channel_type, direction, type, text, status, created_at. For event entries: id, type, chat_id, channel_id, channel_type, data, occurred_at.

has_moreoptionalboolean
next_cursoroptionalstring | null

Response codes

200Timeline page
401Your API key is missing or invalid. Pass it as a bearer token.
404No contact was found with the provided `contactId`.

Sends a live request with your values and shows the real response below. Your key is stored only in this browser.

Request
curl -X GET https://api.blooio.com/v4/contacts/ct_a1b2c3d4/timeline?limit=50&cursor=string&include_events=false \
Response objectexample
{  "data": [    {      "type": "message",      "occurred_at": 0,      "id": "obj_a1b2c3d4",      "chat_id": "chat_a1b2c3d4",      "channel_id": "ch_a1b2c3d4",      "channel_type": "string",      "object": {}    }  ],  "has_more": true,  "next_cursor": "string"}