Get conversation by ID

GET

/api/conversations/{id}

• Production

Retrieves a single conversation with its full details including the linked contact and account information, message history, and attention items. Contact and account data is fetched in parallel from the CRM service and enriched in the response.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

The unique identifier of the conversation to retrieve.

Responses

200

The conversation was found and returned with enriched contact/account data.

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: ‘open’, ‘in_progress’, ‘awaiting_contact’, ‘resolved’, ‘closed’, ‘abandoned’.

string

Example

open

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

404

No conversation exists with the given ID in the authenticated tenant. An API key restricted to a brand or workspace receives the same answer for a conversation in a workspace outside its restriction.

Standard error response returned by all endpoints on failure.

object

error

required

A human-readable error message describing what went wrong.

string

Example

Conversation not found

code

A machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.

string

Example

key_lock

missing_scopes

On a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.

Array<string>

Example

[
  "mcp:write"
]

entryId

On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.

string format: uuid

Example

11223344-5566-4788-99aa-bbccddeeff00

connectionId

On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.

string

undeclaredTools

On the same 422: the tool names the connection does not declare.

Array<string>

Example

[
  "get_orders"
]

declaredTools

On the same 422: the tools the connection declares.

Array<string>

Example

[
  "get_order",
  "search_orders"
]