> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/api-reference/reference/objects/conversation.md).

# The conversation object

The conversation object in the Shortcut API - every field, an example, and the endpoints that return it.

A text or email thread with a customer or lead in the Inbox.

## Fields

| Field                | Type                                                 | Description                                                                           |
| -------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `id`                 | id                                                   | The conversation's id.                                                                |
| `object`             | `"conversation"`                                     | Always `conversation`.                                                                |
| `customerId`         | id or null                                           | The customer it is with, when it is matched to one.                                   |
| `leadId`             | id or null                                           | The lead it is with, when it is matched to one.                                       |
| `displayName`        | string or null                                       | The name the Inbox shows.                                                             |
| `phone`              | string or null                                       | The phone number texts go to, E.164.                                                  |
| `email`              | string or null                                       | The email address, for a conversation that started by email.                          |
| `status`             | `active`, `pending_reply`, `opted_out`, `unresolved` | Where the conversation stands in the Inbox.                                           |
| `optedOut`           | boolean                                              | Whether the customer texted STOP. No text can be sent to them until they opt back in. |
| `lastMessageAt`      | timestamp or null                                    | When the newest message was sent or received.                                         |
| `lastMessagePreview` | string or null                                       | The start of the newest message.                                                      |
| `createdAt`          | timestamp                                            | When the conversation started, ISO 8601 in UTC.                                       |
| `updatedAt`          | timestamp                                            | When it last changed, ISO 8601 in UTC.                                                |

## Example

```json
{
  "id": "4f265d2a-4b70-4871-87ba-d3b844050eff",
  "object": "conversation",
  "customerId": "e0cb8c2e-dd15-4775-8960-02bcd5aa3e03",
  "leadId": "af150a30-ab5f-4577-87a9-80bea3f3bc05",
  "displayName": "Example displayName",
  "phone": "(406) 555-0142",
  "email": "robin.alvarez@example.com",
  "status": "active",
  "optedOut": true,
  "lastMessageAt": null,
  "lastMessagePreview": "Example lastMessagePreview",
  "createdAt": "2026-10-16T17:04:12.381Z",
  "updatedAt": "2026-10-16T17:04:12.381Z"
}
```

## Endpoints

| Endpoint                               | What it does                    |
| -------------------------------------- | ------------------------------- |
| `GET /v1/customers/{id}/conversations` | List a customer's conversations |
