List Conversations

curl --request GET \
  --url https://api.bland.ai/v1/sms/conversations \
  --header 'authorization: <authorization>'

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

}

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
    }
  ],
  "errors": null,
  "extra": {
    "pagination": {
      "totalItems": 42,
      "totalPages": 5,
      "currentPage": 1,
      "pageSize": 10
    }
  }
}

GET

sms

conversations

List Conversations

curl --request GET \
  --url https://api.bland.ai/v1/sms/conversations \
  --header 'authorization: <authorization>'

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

}

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
    }
  ],
  "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

string

required

Your API key for authentication.

Query Parameters

number

The page number to retrieve. Defaults to 1.

number

The number of conversations per page. Defaults to 25.

string

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

string

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

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, curr_pathway_id, curr_pathway_version, timed_out_at
operator: one of eq, contains, startsWith, endsWith, gt, gte, lt, lte
value: the filter value

Response

array

A list of conversations matching the query.

string

Unique ID of the conversation.

string

ISO timestamp when the conversation was created.

string

ISO timestamp when the conversation was last updated.

string

The user-facing phone number in the conversation.

string

The assistant’s phone number in the conversation.

object

Arbitrary variables associated with the conversation.

string

ID of the current node in the conversational pathway.

string|null

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

boolean

Indicates whether the conversation is still active.

number

Number of messages in the conversation.

string|null

The content of the most recent message, if available.

string|null

The timestamp of the most recent message.

array|null

Tags from pathway nodes visited during the conversation.

string|null

The resolved delivery channel: "sms", "rcs", or "whatsapp".

string|null

AI-generated conversation summary, if available.

object|null

Extracted citation variable values, if citation schemas were configured.

string|null

The first successful outcome result tag, if outcomes were configured.

null|array

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

number

Total number of conversations matching the query.

number

Total number of pages available.

number

The current page of the response.

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",
      "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
    }
  ],
  "errors": null,
  "extra": {
    "pagination": {
      "totalItems": 42,
      "totalPages": 5,
      "currentPage": 1,
      "pageSize": 10
    }
  }
}

Docs for agents: llms.txt

⌘I

Basic Tutorials

Calls

Conversational Pathways

Knowledge Bases

Numbers

Blocked Numbers

Widgets

Tools

Contacts

Memory

Node tests

Agent Testing

Evals

Guard Rails

Web Agents

Live Translation

Custom Twilio Accounts

Batches

Prompts

Account

Organizations

Messaging

SIP Trunks

Custom Dialing Pools

Personas

Citation Schemas

Alarms

Triage

List Conversations

Headers

Query Parameters

Response

​Headers

​Query Parameters

​Response

Headers

Query Parameters

Response