GET
/
v1
/
sms
/
conversations
List 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
    }
  }
}
Enterprise Feature - SMS is only available on Enterprise plans. Contact your Bland representative for access.

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
    }
  }
}