Skip to main content
GET
/
v1
/
sms
/
conversations
/
{id}
Get Conversation by ID
curl --request GET \
  --url https://api.bland.ai/v1/sms/conversations/{id} \
  --header 'authorization: <authorization>'
{
  "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
}
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.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.
{
  "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
}