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

# Get Conversation by ID

> Retrieve a single SMS conversation and its messages by its ID

> [!NOTE]
>
> **Enterprise Feature** - SMS is only available on Enterprise plans. Contact your Bland representative for access.

### Headers

**authorization** `string` *required*

Your API key for authentication

### Path Parameters

**id** `string` *required*

The unique ID of the conversation to retrieve.

### Response

**data** `object`

The full conversation object, including its messages.

**data.id** `string`

The unique ID of the conversation.

**data.created\_at** `string`

ISO timestamp for when the conversation was created.

**data.updated\_at** `string`

ISO timestamp for when the conversation was last updated.

**data.user\_number** `string`

The user's phone number in the conversation.

**data.agent\_number** `string`

The assistant's phone number in the conversation.

**data.variables** `object|null`

Variables stored on the conversation, or `null` if none.

**data.current\_node\_id** `string|null`

The current node ID in the pathway, if any.

**data.curr\_pathway\_id** `string|null`

The UUID of the current pathway being used in this conversation.

**data.curr\_pathway\_version** `string|null`

The specific version of the pathway being used (e.g., "latest", "v1.0").

**data.timed\_out\_at** `string|null`

ISO timestamp when the conversation timed out due to inactivity, if applicable. When set, the conversation will not respond to new user messages but will store them.

**data.is\_active** `boolean`

Whether the conversation is still active.

**data.human\_handoff\_at** `string|null`

ISO timestamp set while a human owns the thread. The agent does not reply until the conversation is [resumed](https://docs.bland.ai/api-v1/post/sms-conversations-resume.md). Messages sent by the rep have `sender: "HUMAN"`.

**data.human\_handoff\_reason** `string|null`

Reason supplied at handoff, if any.

**data.human\_handoff\_metadata** `object|null`

`source` (`"api"`, `"node"`, or `"dashboard"`), optional `actor`, plus any metadata passed at handoff.

**data.effective\_channel** `string|null`

The resolved delivery channel for this conversation: `"sms"`, `"rcs"`, or `"whatsapp"`. Determined based on the input channel and whether the messaging service supports RCS.

**data.summary** `string|null`

AI-generated conversation summary, produced when the conversation ends and a summary prompt is configured on the SMS number.

**data.citation\_variables** `object|null`

Extracted citation variable values from the conversation transcript. Keys are variable names, values are the extracted data. Only populated when citation schemas are configured.

**data.disposition\_tag** `string|null`

The first successful outcome result tag. Provides a quick classification of the conversation outcome without needing to inspect the full `disposition_logs`.

**data.messages** `array`

An array of message objects in the conversation, sorted chronologically.

**data.messages\[].id** `string`

Unique ID of the message.

**data.messages\[].created\_at** `string`

ISO timestamp of when the message was created.

**data.messages\[].message** `string`

The message body.

**data.messages\[].from** `string`

Sender phone number.

**data.messages\[].to** `string`

Receiver phone number.

**data.messages\[].sender** `string`

Either `"USER"` or `"AGENT"` to indicate who sent the message.

**data.messages\[].status** `string`

Delivery status of the message. Possible values: `"pending"`, `"queued"`, `"sent"`, `"delivered"`, `"read"`, `"failed"`, `"undelivered"`. The `"read"` status is available for RCS and WhatsApp channels.

**data.messages\[].error\_code** `string|null`

Twilio error code if the message failed, otherwise `null`.

**data.disposition\_logs** `array`

An array of outcome run results for this conversation. Each entry represents one outcome that was evaluated when the conversation ended.

**data.disposition\_logs\[].disposition\_id** `string`

The ID of the outcome that was run.

**data.disposition\_logs\[].snippet\_version** `number`

The version of the outcome's transformation code that was executed.

**data.disposition\_logs\[].status** `string`

The execution status. `"COMPLETE"` indicates the outcome ran successfully, `"ERROR"` indicates a failure.

**data.disposition\_logs\[].result** `object|null`

The extracted outcome values, or `null` if the run failed.

**data.disposition\_logs\[].error** `string|null`

Error message if the outcome run failed, otherwise `null`.

**data.disposition\_logs\[].exec\_time** `number`

Execution time in milliseconds.

**errors** `null|array`

`null` on success, or a list of error objects if a failure occurred.

```json Response theme={null}
{
  "data": {
    "id": "convo_abc123",
    "created_at": "2025-05-13T20:50:59.233Z",
    "updated_at": "2025-05-13T20:50:59.233Z",
    "user_id": "user_abc123",
    "user_number": "+15550001111",
    "agent_number": "+15550002222",
    "inbound_id": 123456,
    "variables": null,
    "current_node_id": null,
    "curr_pathway_id": "pathway_abc123",
    "curr_pathway_version": "latest",
    "timed_out_at": null,
    "last_message_at": "2025-05-13T20:50:59.233Z",
    "is_active": true,
    "effective_channel": "sms",
    "summary": null,
    "citation_variables": null,
    "disposition_tag": null,
    "messages": [
      {
        "created_at": "2025-05-13T20:50:59.708Z",
        "message": "<Call Connected>",
        "from": "+15550002222",
        "to": "+15550001111",
        "sender": "USER",
        "id": 100001,
        "status": null,
        "error_code": null
      },
      {
        "created_at": "2025-05-13T20:51:00.917Z",
        "message": "Hey, what's up?",
        "from": "+15550002222",
        "to": "+15550001111",
        "sender": "AGENT",
        "id": 100002,
        "status": "delivered",
        "error_code": null
      }
    ],
    "disposition_logs": [
      {
        "disposition_id": "d1234567-abcd-1234-efgh-123456789012",
        "snippet_version": 1,
        "status": "COMPLETE",
        "result": {
          "appointmentBooked": true,
          "callDisposition": "confirmed"
        },
        "error": null,
        "exec_time": 1234
      }
    ]
  },
  "errors": null
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.