> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bland.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Listen to Active Call

> Initiate a live listen session for an active call

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`

**data properties**

**url** `string`

WebSocket URL for connecting to the live audio stream

**errors** `array` (default: null)

Array of error objects if request failed

```bash cURL theme={null}
curl -X POST "https://api.bland.ai/v1/calls/call_123456/listen" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

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

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

```python Python theme={null}
import requests

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

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

```json Success Response theme={null}
{
  "status": "success",
  "data": {
    "url": "wss://api.bland.ai/ws/listen/call_123456"
  },
  "errors": null
}
```

```json Organization Not Configured theme={null}
{
  "status": "error",
  "data": null,
  "errors": [
    {
      "error": "INVALID_ORG_PREFERENCES",
      "message": "Org preferences do not allow live listening"
    }
  ]
}
```

```json Call Not Found theme={null}
{
  "status": "error", 
  "data": null,
  "errors": [
    {
      "error": "CALL_NOT_FOUND",
      "message": "Call not found"
    }
  ]
}
```

```json Call Not Active theme={null}
{
  "status": "error",
  "data": null, 
  "errors": [
    {
      "error": "INVALID_CALL_STATUS",
      "message": "Call is not in progress"
    }
  ]
}
```

```json Call Not Available for Streaming theme={null}
{
  "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

```javascript theme={null}
// 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](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.