For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.telcoflow.com/reference/llms.txt. For full documentation content, see https://docs.telcoflow.com/reference/llms-full.txt.

# API Reference

## TelcoflowClientConfig

The public `0.24.0` docs present `TelcoflowClientConfig` through factory helpers rather than direct constructor examples.

### Factory Helpers

| Helper | Use | Parameters |
|---|---|---|
| `TelcoflowClientConfig.sandbox(...)` | SANDBOX mode with API key authentication | `api_key`, `connector_uuid`, `sample_rate` |
| `TelcoflowClientConfig.production(...)` | PROD mode with mTLS authentication | `cert_path`, `key_path`, `sample_rate` |

### Examples

```python
sandbox_config = TelcoflowClientConfig.sandbox(
    api_key="YOUR_API_KEY",
    connector_uuid="YOUR_CONNECTOR_UUID",
    sample_rate=24000,
)

production_config = TelcoflowClientConfig.production(
    cert_path="/etc/certs/client.pem",
    key_path="/etc/certs/client.key",
    sample_rate=24000,
)
```

---

## TelcoflowClient

Main client class for managing the control connection and dispatching call events.

### Methods

| Method | Description |
|---|---|
| `run_forever()` | Run until the client is closed. Use this inside `async with TelcoflowClient(config) as client:` for long-lived apps |
| `connect()` | Explicitly open the control connection |
| `disconnect()` | Explicitly close the control connection |
| `on(event)` | Decorator for client-level handlers such as `events.INCOMING_CALL` or `ClientEvent.INCOMING_CALL` |
| `get_call(call_id)` | Get an active call by ID |

### Context Manager

```python
async with TelcoflowClient(config) as client:
    @client.on(events.INCOMING_CALL)
    async def on_call(call):
        await call.answer()

    await client.run_forever()
```

---

## ActiveCall

Represents a call session with an attached media connection.

### Methods

| Method | Parameters | Description |
|---|---|---|
| `answer()` | | Answer the incoming call |
| `connect()` | `ring_time_seconds=60` | Initiate a 3-way conference between the caller, callee, and agent |
| `whisper()` | | Route the agent's audio to the callee only |
| `barge()` | | Route the agent's audio to both caller and callee |
| `spy()` | | Put the agent in listen-only mode |
| `disconnect()` | | End the call for all parties |
| `close()` | | Close the call and release resources. After `connect()`, the agent leaves while caller and callee stay connected. After `answer()` without `connect()`, the call ends for both agent and caller |
| `force_disconnect()` | | Forcefully tear down the call from the client side |
| `send_audio()` | `audio_data: bytes` | Queue raw PCM audio for playback |
| `clear_send_audio_buffer()` | | Clear all queued outgoing audio |
| `get_send_audio_buffer_size()` | | Return the current queued buffer size |
| `audio_stream()` | | Async iterator for incoming audio chunks |
| `on(event)` | `handler` | Decorator for call-level event handlers such as `events.CALL_TERMINATED` or `CallEvent.CALL_TERMINATED` |

### Properties

| Property | Type | Description |
|---|---|---|
| `call_id` | `str` | Unique call identifier |
| `caller_number` | `str` | Caller phone number |
| `callee_number` | `str` | Callee phone number |
| `direction` | `str` | Call direction, such as `"MT"` |

---

## Events

All string event constants are available from `telcoflow_sdk.events`:

```python
import telcoflow_sdk.events as events
```

The public `0.24.0` package docs also describe `ClientEvent` and `CallEvent` enums as type-safe alternatives to these string constants.

| Event | Level | Description |
|---|---|---|
| `events.INCOMING_CALL` | Client | A new call has arrived |
| `events.CALL_TERMINATED` | Call | The call has ended |
| `events.CALL_ANSWERED` | Call | The call was successfully answered |
| `events.CALL_CONNECTED` | Call | The connect operation succeeded |
| `events.CALL_CONNECT_FAILED` | Call | The connect operation failed |
| `events.CALL_ANSWER_FAILED` | Call | The answer attempt failed |

## Next Steps

- [Call States](/concepts/call-states-and-lifecycle) - See how these methods map to the call lifecycle
- [Error Handling](/reference/error-handling) - Review the exception hierarchy and recovery patterns
- [Advanced Topics](/reference/advanced-topics) - Logging, concurrency, and operational notes