Listen to Active Call

curl -X POST "https://api.bland.ai/v1/calls/call_123456/listen" \
  -H "Authorization: YOUR_API_KEY"

const response = await fetch('https://api.bland.ai/v1/calls/call_123456/listen', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data.data.url); // WebSocket URL

import requests

url = "https://api.bland.ai/v1/calls/call_123456/listen"
headers = {"Authorization": "YOUR_API_KEY"}

response = requests.post(url, headers=headers)
data = response.json()
print(data["data"]["url"])  # WebSocket URL

{
  "status": "success",
  "data": {
    "url": "wss://api.bland.ai/ws/listen/call_123456"
  },
  "errors": null
}

{
  "status": "error",
  "data": null,
  "errors": [
    {
      "error": "INVALID_ORG_PREFERENCES",
      "message": "Org preferences do not allow live listening"
    }
  ]
}

{
  "status": "error", 
  "data": null,
  "errors": [
    {
      "error": "CALL_NOT_FOUND",
      "message": "Call not found"
    }
  ]
}

{
  "status": "error",
  "data": null, 
  "errors": [
    {
      "error": "INVALID_CALL_STATUS",
      "message": "Call is not in progress"
    }
  ]
}

{
  "status": "error",
  "data": null,
  "errors": [
    {
      "error": "CALL_NOT_FOUND", 
      "message": "Call was either not found or not started"
    }
  ]
}

POST

calls

{call_id}

listen

curl -X POST "https://api.bland.ai/v1/calls/call_123456/listen" \
  -H "Authorization: YOUR_API_KEY"

const response = await fetch('https://api.bland.ai/v1/calls/call_123456/listen', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data.data.url); // WebSocket URL

import requests

url = "https://api.bland.ai/v1/calls/call_123456/listen"
headers = {"Authorization": "YOUR_API_KEY"}

response = requests.post(url, headers=headers)
data = response.json()
print(data["data"]["url"])  # WebSocket URL

{
  "status": "success",
  "data": {
    "url": "wss://api.bland.ai/ws/listen/call_123456"
  },
  "errors": null
}

{
  "status": "error",
  "data": null,
  "errors": [
    {
      "error": "INVALID_ORG_PREFERENCES",
      "message": "Org preferences do not allow live listening"
    }
  ]
}

{
  "status": "error", 
  "data": null,
  "errors": [
    {
      "error": "CALL_NOT_FOUND",
      "message": "Call not found"
    }
  ]
}

{
  "status": "error",
  "data": null, 
  "errors": [
    {
      "error": "INVALID_CALL_STATUS",
      "message": "Call is not in progress"
    }
  ]
}

{
  "status": "error",
  "data": null,
  "errors": [
    {
      "error": "CALL_NOT_FOUND", 
      "message": "Call was either not found or not started"
    }
  ]
}

Starts a live listen session for an active call, returning a WebSocket URL for real-time audio streaming.

Authentication

authorization

string

required

Your API key for authentication

Path Parameters

call_id

string

required

The unique identifier of the call to listen to

Prerequisites

Live listen must be enabled in organization preferences (live_listen_enabled: true)
Call must be in active status (not completed)
Call must belong to the authenticated organization

Response

status

string

Response status indicator

data

object

Show data properties

url

string

WebSocket URL for connecting to the live audio stream

errors

array

default:"null"

Array of error objects if request failed

curl -X POST "https://api.bland.ai/v1/calls/call_123456/listen" \
  -H "Authorization: YOUR_API_KEY"

const response = await fetch('https://api.bland.ai/v1/calls/call_123456/listen', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data.data.url); // WebSocket URL

import requests

url = "https://api.bland.ai/v1/calls/call_123456/listen"
headers = {"Authorization": "YOUR_API_KEY"}

response = requests.post(url, headers=headers)
data = response.json()
print(data["data"]["url"])  # WebSocket URL

{
  "status": "success",
  "data": {
    "url": "wss://api.bland.ai/ws/listen/call_123456"
  },
  "errors": null
}

{
  "status": "error",
  "data": null,
  "errors": [
    {
      "error": "INVALID_ORG_PREFERENCES",
      "message": "Org preferences do not allow live listening"
    }
  ]
}

{
  "status": "error", 
  "data": null,
  "errors": [
    {
      "error": "CALL_NOT_FOUND",
      "message": "Call not found"
    }
  ]
}

{
  "status": "error",
  "data": null, 
  "errors": [
    {
      "error": "INVALID_CALL_STATUS",
      "message": "Call is not in progress"
    }
  ]
}

{
  "status": "error",
  "data": null,
  "errors": [
    {
      "error": "CALL_NOT_FOUND", 
      "message": "Call was either not found or not started"
    }
  ]
}

WebSocket Connection

After receiving the WebSocket URL, connect to it to receive real-time audio data:

Connection Details

URL: Use the url returned in the response
Protocol: WebSocket (WSS)
Binary Type: arraybuffer
Authentication: Handled via the URL token

Audio Data Format

The WebSocket streams binary audio data with these specifications:

Format: PCM Int16 (16-bit signed integers)
Sample Rate: 16,000 Hz
Channels: Mono (1 channel)
Byte Order: Little-endian
Data: Combined audio from all call participants

WebSocket Implementation Example

// Connect to WebSocket
const socket = new WebSocket(websocketUrl);
socket.binaryType = 'arraybuffer';

socket.onmessage = (event) => {
  // Convert ArrayBuffer to Int16Array
  const dataView = new DataView(event.data);
  const int16Array = new Int16Array(dataView.byteLength / 2);
  
  for (let i = 0; i < int16Array.length; i++) {
    int16Array[i] = dataView.getInt16(i * 2, true); // Little-endian
  }
  
  // Process audio data (convert to Float32 for Web Audio API)
  const float32Array = new Float32Array(int16Array.length);
  for (let i = 0; i < int16Array.length; i++) {
    float32Array[i] = int16Array[i] / 32768; // Normalize to [-1, 1]
  }
  
  // Use audio data for playback
};

socket.onclose = () => {
  console.log('Live listen session ended');
};

Error Codes

Error Code	Description
`MISSING_CALL_ID`	Call ID parameter is required
`INVALID_ORG_PREFERENCES`	Live listen is not enabled for organization
`CALL_NOT_FOUND`	Call does not exist or does not belong to organization
`INVALID_CALL_STATUS`	Call is not currently active
`INTERNAL_SERVER_ERROR`	Server error occurred

Notes

WebSocket connection automatically closes when the call ends
Multiple concurrent listeners can subscribe to the same call
Audio stream includes all participants in the call (combined)
The WebSocket URL can be used by multiple connections simultaneously

Docs for agents: llms.txt

Stop Active Call Stop All Active Calls

⌘I

​Authentication

​Path Parameters

​Prerequisites

​Response

​WebSocket Connection

​Connection Details

​Audio Data Format

​WebSocket Implementation Example

​Error Codes

​Notes

Authentication

Path Parameters

Prerequisites

Response

WebSocket Connection

Connection Details

Audio Data Format

WebSocket Implementation Example

Error Codes

Notes