> ## Documentation Index
> Fetch the complete documentation index at: https://docs.custral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Conversation object

> Threads of messages: a chat, a call, an email exchange, or your own bridged channel.

A conversation is a thread of messages with a lifecycle `status` and an optional
`outcome`. The endpoints in this section let you **view** conversations, **manage**
their status and outcome, and **ingest** your own. Create a conversation and
append messages into it, the loop a custom bridge (e.g. an iMessage or WhatsApp
middleware) runs.

<ResponseExample>
  ```json The Conversation object theme={null}
  {
    "id": "conv_3Ab9xK2mQ7",
    "title": "Jane Doe",
    "status": "open",
    "outcome": null,
    "summary": null,
    "sourceType": "imessage",
    "channelId": null,
    "startedAt": "2026-08-09T12:00:00.000Z",
    "endedAt": null,
    "createdAt": "2026-08-09T12:00:00.000Z",
    "updatedAt": "2026-08-09T12:00:00.000Z",
    "messages": [
      {
        "id": "msg_5Cd2yL8nR2",
        "text": "Hey, still on for Friday?",
        "author": "Jane Doe",
        "authorId": "+15551234567",
        "sourceType": "imessage",
        "direction": "inbound",
        "timestamp": "2026-08-09T12:00:00.000Z"
      }
    ],
    "participants": [
      { "type": "guest", "name": "Jane Doe", "email": "jane@example.com", "recordId": null }
    ]
  }
  ```
</ResponseExample>

## Attributes

<ResponseField name="id" type="string">
  Unique identifier, prefixed `conv_`.
</ResponseField>

<ResponseField name="title" type="string | null">
  A human-readable title. The contact's name or the thread subject.
</ResponseField>

<ResponseField name="status" type="string">
  Lifecycle state. You may **set** `open`, `closed`, or `completed`; the states
  `processing`, `pending_action`, and `failed` are owned by Custral's analysis
  pipeline and are read-only.
</ResponseField>

<ResponseField name="outcome" type="string | null">
  The conversation's outcome, a disposition `key` such as `won`, or `null`. The
  **List dispositions** endpoint returns the valid keys.
</ResponseField>

<ResponseField name="summary" type="string | null">
  An AI-generated summary, once the conversation has been analysed.
</ResponseField>

<ResponseField name="sourceType" type="string | null">
  A free-form source label. Conversations you create default to `api`; pass your
  own (e.g. `imessage`) to tag the channel your bridge feeds from.
</ResponseField>

<ResponseField name="channelId" type="string | null">
  The channel (`chan_`) the conversation is attached to, if any.
</ResponseField>

<ResponseField name="startedAt" type="string | null">
  ISO 8601 timestamp of the first message.
</ResponseField>

<ResponseField name="endedAt" type="string | null">
  ISO 8601 timestamp of the last message, or `null` while still open.
</ResponseField>

<ResponseField name="messages" type="array">
  The transcript. Present on **retrieve** and **create**; omitted from list rows.

  <Expandable title="message properties">
    <ResponseField name="id" type="string">The message id, prefixed `msg_`.</ResponseField>
    <ResponseField name="text" type="string">The message body.</ResponseField>
    <ResponseField name="author" type="string | null">Display name of the sender.</ResponseField>
    <ResponseField name="authorId" type="string | null">A stable handle for the sender: phone, email, or record id.</ResponseField>
    <ResponseField name="sourceType" type="string | null">Inherited from the conversation's `sourceType`.</ResponseField>
    <ResponseField name="direction" type="string | null">`inbound` (from the contact) or `outbound` (from your side).</ResponseField>
    <ResponseField name="timestamp" type="string | null">ISO 8601 send time.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="participants" type="array">
  Who is on the conversation. Present on the detail shape.

  <Expandable title="participant properties">
    <ResponseField name="type" type="string | null">`record`, `guest`, or `user`.</ResponseField>
    <ResponseField name="name" type="string | null">Display name (a guest's name, or the linked record's).</ResponseField>
    <ResponseField name="email" type="string | null">The guest's email, when there's no linked record.</ResponseField>
    <ResponseField name="recordId" type="string | null">The linked record (`rec_`), set only for a `record` participant.</ResponseField>
  </Expandable>
</ResponseField>


## Related topics

- [Conversation](/data/properties/select/conversation.md)
- [Conversation Table](/blocks/embedded/conversations/conversation-table.md)
- [Inbox](/comms/inbox/overview.md)
- [Retrieve a conversation](/api-reference/conversations/retrieve-a-conversation.md)
- [Create a conversation](/api-reference/conversations/create-a-conversation.md)