Messaging
List Conversations
Retrieve a paginated list of SMS conversations for the authenticated user, with filtering, sorting, and metadata.
GET
/
v1
/
sms
/
conversations
List Conversations
curl --request GET \
--url https://api.bland.ai/v1/sms/conversations \
--header 'authorization: <authorization>'import requests
url = "https://api.bland.ai/v1/sms/conversations"
headers = {"authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {authorization: '<authorization>'}};
fetch('https://api.bland.ai/v1/sms/conversations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.bland.ai/v1/sms/conversations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.bland.ai/v1/sms/conversations"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.bland.ai/v1/sms/conversations")
.header("authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v1/sms/conversations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"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",
"curr_pathway_id": "pathway_abc123",
"is_active": true,
"message_count": 5,
"last_message": "Hi there, how can I help you?",
"last_message_at": "2024-11-21T09:12:00.000Z",
"pathway_tags": [{"name": "Greeting", "color": "#4287f5"}],
"effective_channel": "sms",
"summary": null,
"citation_variables": null,
"disposition_tag": null,
"agent_id": null,
"agent_version_id": null
}
],
"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
Query Parameters
The number of conversations to skip before the first one returned. Use it with
limit to page through results. Defaults to 0.Field to sort by. Allowed values:
created_at, updated_at, last_message_at, message_count. Defaults to created_at.A JSON-encoded array of filter objects. Each object should contain:
field: one ofcreated_at,updated_at,user_number,agent_number,is_active,message_count,variables,current_node_id,curr_pathway_id,curr_pathway_version,timed_out_at,agent_id,agentoperator: one ofequals,not,in,notIn,contains,startsWith,endsWith,gt,gte,lt,lte,isEmpty,isNotEmpty,hasSome,hasEvery,none. An operator outside the accepted set fails with400and error codeINVALID_PARAMETER.value: the filter value.inandnotIntake an array.
agent_id with equals or in. agent_id takes equals, not, in, notIn, isEmpty, and isNotEmpty, and its value must be a UUID. The agent field also matches conversations created before the agent was recorded on them, and takes equals or in.Response
The V2 agent the conversation ran, or
null for a pathway or persona conversation. On an agent conversation, citation_variables and disposition_tag stay empty, and curr_pathway_id can be an ID that Bland manages for the agent rather than a pathway you created.The agent’s Dispositions results for the conversation. Present only when your organization has Dispositions enabled and the page includes an agent conversation. Empty on a conversation that ran no agent.
{
"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",
"curr_pathway_id": "pathway_abc123",
"is_active": true,
"message_count": 5,
"last_message": "Hi there, how can I help you?",
"last_message_at": "2024-11-21T09:12:00.000Z",
"pathway_tags": [{"name": "Greeting", "color": "#4287f5"}],
"effective_channel": "sms",
"summary": null,
"citation_variables": null,
"disposition_tag": null,
"agent_id": null,
"agent_version_id": null
}
],
"errors": null,
"extra": {
"pagination": {
"totalItems": 42,
"totalPages": 5,
"currentPage": 1,
"pageSize": 10
}
}
}
Docs for agents: llms.txt
Was this page helpful?
⌘I
List Conversations
curl --request GET \
--url https://api.bland.ai/v1/sms/conversations \
--header 'authorization: <authorization>'import requests
url = "https://api.bland.ai/v1/sms/conversations"
headers = {"authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {authorization: '<authorization>'}};
fetch('https://api.bland.ai/v1/sms/conversations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.bland.ai/v1/sms/conversations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.bland.ai/v1/sms/conversations"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.bland.ai/v1/sms/conversations")
.header("authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v1/sms/conversations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"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",
"curr_pathway_id": "pathway_abc123",
"is_active": true,
"message_count": 5,
"last_message": "Hi there, how can I help you?",
"last_message_at": "2024-11-21T09:12:00.000Z",
"pathway_tags": [{"name": "Greeting", "color": "#4287f5"}],
"effective_channel": "sms",
"summary": null,
"citation_variables": null,
"disposition_tag": null,
"agent_id": null,
"agent_version_id": null
}
],
"errors": null,
"extra": {
"pagination": {
"totalItems": 42,
"totalPages": 5,
"currentPage": 1,
"pageSize": 10
}
}
}