Skip to main content
GET
List conversations

Authorizations

Authorization
string
header
required

A workspace API token (sk_live_...) or an OAuth access token (oat_live_...). Create workspace tokens in Settings > API. Send either as Authorization: Bearer <token>.

Query Parameters

status
enum<string>[] | null

Only conversations in this status. Repeat to match any of several.

Where a conversation stands.

waiting: open, and nobody has picked it up yet — it is in a queue, or assigned to a teammate who has not accepted it. active: open and being handled, by the AI agent or by a teammate. closed: finished.

Available options:
waiting,
active,
closed
channel
enum<string>[] | null

Only conversations on this platform. Repeat to match any of several.

The messaging platform a channel runs on.

whatsapp_api is the official WhatsApp Business Platform, the only one that supports message templates. whatsapp is a number connected through the WhatsApp app. botconversa is a channel fed by an external chatbot integration.

Available options:
whatsapp_api,
whatsapp,
instagram,
slack,
web_widget,
botconversa
channel_id
string[] | null

Only conversations on this channel. Repeat to match any of several.

Unique identifier for a channel.

Pattern: ^chn_[0-9a-f]{32}$
contact_id
string[] | null

Only conversations with this contact. Repeat to match any of several.

Unique identifier for a contact.

Pattern: ^con_[0-9a-f]{32}$
campaign_id
string[] | null

Only conversations this campaign started. Repeat to match any of several.

Unique identifier for a campaign.

Pattern: ^camp_[0-9a-f]{32}$
needs_human
boolean | null

Only open conversations where needs_human has this value. To find conversations by who handles them, use handler.

handler
enum<string>[] | null

Only conversations whose handler is of this kind: agent (the AI agent), user (a teammate) or none (nobody: waiting in a queue, or closed). Repeat to match any of several.

Who handles a conversation: the AI agent, a teammate, or nobody.

Available options:
agent,
user,
none
updated_since
string<date-time> | null

Only conversations whose updated_at is at or after this instant. Must include a timezone offset.

sort
string | null

Ordering key, - prefix for descending. One of: last_message_at, created_at. Default -last_message_at; conversations with no messages sort last either way.

Example:

"-last_message_at"

limit
integer
default:50

Items per page (max 200).

Required range: 1 <= x <= 200
cursor
string | null

Opaque cursor from a previous response's links.next.

Response

Successful Response

A page of conversations.

data
Conversation · object[]
required
meta
PageMeta · object
required