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"
}
]
}
Calls
Listen to Active Call
Initiate a live listen session for an active call
POST
/
v1
/
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.
Docs for agents: llms.txt
Authentication
string
required
Your API key for authentication
Path Parameters
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
string
Response status indicator
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
urlreturned 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
Was this page helpful?