GET
/
v1
/
sms
/
conversations
curl --request GET \
  --url https://api.bland.ai/v1/sms/conversations \
  --header 'authorization: <authorization>'
{
  "data": [
    {
      "id": "convo_abc123",
      "created_at": "2024-11-20T14:01:00.000Z",
      "updated_at": "2024-11-21T09:12:00.000Z",
      "user_number": "+15550001111",
      "agent_number": "+15552223333",
      "variables": { "campaign_id": "xyz789" },
      "current_node_id": "node_intro",
      "is_active": true,
      "message_count": 5,
      "last_message": "Hi there, how can I help you?",
      "last_message_timestamp": "2024-11-21T09:12:00.000Z",
      "pathway_id": "pathway_support"
    }
  ],
  "errors": null,
  "extra": {
    "pagination": {
      "totalItems": 42,
      "totalPages": 5,
      "currentPage": 1,
      "pageSize": 10
    }
  }
}

​
Headers

​
authorization
string
required

Your API key for authentication.

​
Query Parameters

​
page
number

The page number to retrieve. Defaults to 1.

​
pageSize
number

The number of conversations per page. Defaults to 25.

​
sortBy
string

Field to sort by. Allowed values: created_at, updated_at, user_number, agent_number, is_active, message_count. Defaults to created_at.

​
sortDir
string

Direction of sorting. Either asc or desc. Defaults to desc.

​
filters
object[]

A JSON-encoded array of filter objects. Each object should contain:

  • field: one of created_at, updated_at, user_number, agent_number, is_active, message_count, variables, current_node_id
  • operator: one of eq, contains, startsWith, endsWith, gt, gte, lt, lte
  • value: the filter value

​
Response

​
data
array

A list of conversations matching the query.

​
data[].id
string

Unique ID of the conversation.

​
data[].created_at
string

ISO timestamp when the conversation was created.

​
data[].updated_at
string

ISO timestamp when the conversation was last updated.

​
data[].user_number
string

The user-facing phone number in the conversation.

​
data[].agent_number
string

The assistant’s phone number in the conversation.

​
data[].variables
object

Arbitrary variables associated with the conversation.

​
data[].current_node_id
string

ID of the current node in the conversational pathway.

​
data[].is_active
boolean

Indicates whether the conversation is still active.

​
data[].message_count
number

Number of messages in the conversation.

​
data[].last_message
string|null

The content of the most recent message, if available.

​
data[].last_message_timestamp
string|null

The timestamp of the most recent message.

​
data[].pathway_id
string

Optional ID of the conversational pathway, if configured.

​
data[].convo_pathways
object

Optional pathway metadata if available.

​
errors
null|array

null on success, or a list of errors on failure.

​
extra.pagination.totalItems
number

Total number of conversations matching the query.

​
extra.pagination.totalPages
number

Total number of pages available.

​
extra.pagination.currentPage
number

The current page of the response.

​
extra.pagination.pageSize
number

Number of items per page in the current response.

{
  "data": [
    {
      "id": "convo_abc123",
      "created_at": "2024-11-20T14:01:00.000Z",
      "updated_at": "2024-11-21T09:12:00.000Z",
      "user_number": "+15550001111",
      "agent_number": "+15552223333",
      "variables": { "campaign_id": "xyz789" },
      "current_node_id": "node_intro",
      "is_active": true,
      "message_count": 5,
      "last_message": "Hi there, how can I help you?",
      "last_message_timestamp": "2024-11-21T09:12:00.000Z",
      "pathway_id": "pathway_support"
    }
  ],
  "errors": null,
  "extra": {
    "pagination": {
      "totalItems": 42,
      "totalPages": 5,
      "currentPage": 1,
      "pageSize": 10
    }
  }
}