List conversations

GET

/api/conversations

• Production

Returns a paginated list of conversations, optionally filtered by workspace, status, or text search. Results are ordered by the most recent activity (lastMessageAt). Use the offset and limit parameters to paginate through large result sets.

Authorizations

• bearerAuth

Parameters

Query Parameters

workspaceId

string format: uuid

Filter conversations to a specific workspace.

status

string

Filter by conversation status. Accepted values: ‘new’, ‘active’, ‘human_managed’, ‘resolved’, ‘waiting’.

limit

integer | null

Maximum number of conversations to return per page. Defaults to 50.

offset

integer | null

Number of conversations to skip before returning results. Defaults to 0.

Responses

200

A paginated list of conversations with the total count of matching results.

Paginated list of conversations. Use the total field to determine how many conversations match your filters, and offset/limit query parameters to page through results.

object

conversations

required

The conversations on the current page.

Array<object>

A conversation represents a threaded exchange between a customer and your organization on a specific channel. Conversations are created automatically when a new inbound message arrives, or manually via the compose endpoint. Each conversation tracks its lifecycle through status transitions and maintains links to the associated contact and account.

object

id

required

Unique identifier for the conversation.

string format: uuid

Example

c1a2b3c4-5678-9abc-def0-1234567890ab

tenantId

required

The tenant this conversation belongs to.

string format: uuid

Example

a0b1c2d3-4567-89ab-cdef-0123456789ab

workspaceId

required

The workspace this conversation is assigned to.

string format: uuid

Example

w1a2b3c4-5678-9abc-def0-1234567890ab

channelId

required

The channel (email, WhatsApp, chat widget, etc.) through which this conversation is conducted.

string format: uuid

Example

ch1a2b3c-5678-9abc-def0-1234567890ab

contactId

The contact (individual person) participating in this conversation. May be null if the contact has not yet been resolved.

string | null format: uuid

Example

ct1a2b3c-5678-9abc-def0-1234567890ab

accountId

The account (company or organization) the contact belongs to. May be null for B2C conversations or if the account has not yet been resolved.

string | null format: uuid

Example

ac1a2b3c-5678-9abc-def0-1234567890ab

status

required

Current lifecycle status of the conversation. Possible values: ‘new’ (just created, no AI response yet), ‘active’ (AI is managing), ‘human_managed’ (a human agent has taken over), ‘resolved’ (closed with an outcome), ‘waiting’ (awaiting customer response).

string

Example

active

summary

AI-generated summary of the conversation, updated after each turn. Provides a concise overview of the discussion so far.

string | null

Example

Customer asked about delivery times for order #4521. Agent confirmed 3-5 business days to Germany.

subject

Subject line of the conversation. For email conversations, this is the email subject. For other channels, it may be AI-generated or null.

string | null

Example

Re: Delivery time for order #4521

outcome

A short description of how the conversation was resolved. Set when the conversation is moved to ‘resolved’ status, either by the AI or a human agent.

string | null

Example

Delivery timeline confirmed, customer satisfied.

messageCount

required

Total number of messages in the conversation thread, including both customer and agent messages.

integer

Example

6

lastMessageAt

Timestamp of the most recent message in the conversation. Null if no messages have been exchanged yet.

string | null format: date-time

Example

2026-03-25T11:42:00.000Z

createdAt

required

Timestamp when the conversation was created.

string format: date-time

Example

2026-03-24T08:15:00.000Z

updatedAt

required

Timestamp when the conversation was last updated (status change, new message, etc.).

string format: date-time

Example

2026-03-25T11:42:00.000Z

total

required

Total number of conversations matching the applied filters, across all pages.

integer

Example

142