The Conversation object

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.

{
  "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 }
  ]
}

Attributes

string

Unique identifier, prefixed conv_.

string | null

A human-readable title. The contact’s name or the thread subject.

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.

string | null

The conversation’s outcome, a disposition key such as won, or null. The List dispositions endpoint returns the valid keys.

string | null

An AI-generated summary, once the conversation has been analysed.

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.

string | null

The channel (chan_) the conversation is attached to, if any.

string | null

ISO 8601 timestamp of the first message.

string | null

ISO 8601 timestamp of the last message, or null while still open.

array

The transcript. Present on retrieve and create; omitted from list rows.

Show message properties

string

The message id, prefixed msg_.

string

The message body.

string | null

Display name of the sender.

string | null

A stable handle for the sender: phone, email, or record id.

string | null

Inherited from the conversation’s sourceType.

string | null

inbound (from the contact) or outbound (from your side).

string | null

ISO 8601 send time.

array

Who is on the conversation. Present on the detail shape.

Show participant properties

string | null

record, guest, or user.

string | null

Display name (a guest’s name, or the linked record’s).

string | null

The guest’s email, when there’s no linked record.

string | null

The linked record (rec_), set only for a record participant.

Introduction

Endpoints

Embeds & real-time

The Conversation object

Attributes

​Attributes

Attributes