POST
/
v1
/
calls
/
{call_id}
/
listen
curl -X POST "https://api.bland.ai/v1/calls/call_123456/listen" \
  -H "Authorization: YOUR_API_KEY"
{
  "status": "success",
  "data": {
    "url": "wss://api.bland.ai/ws/listen/call_123456"
  },
  "errors": null
}
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
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"
{
  "status": "success",
  "data": {
    "url": "wss://api.bland.ai/ws/listen/call_123456"
  },
  "errors": null
}

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 CodeDescription
MISSING_CALL_IDCall ID parameter is required
INVALID_ORG_PREFERENCESLive listen is not enabled for organization
CALL_NOT_FOUNDCall does not exist or does not belong to organization
INVALID_CALL_STATUSCall is not currently active
INTERNAL_SERVER_ERRORServer 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