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

# Telcoflow SDK

Python SDK for connecting to the Telcoflow Server, handling call events, managing media connections, and processing audio streams. These docs track the public `telcoflow-sdk` `0.24.0` package currently published on TestPyPI.

[![PyPI](https://img.shields.io/badge/pypi-telcoflow--sdk-blue)](https://test.pypi.org/project/telcoflow-sdk/)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

## Features

- **Dual authentication** - Support for API key authentication in SANDBOX mode and mTLS certificates in PROD mode
- **Automatic reconnection** - Reconnects when the control connection drops
- **Event-driven call handling** - Decorator-based handlers for call events plus async iterators for audio streams
- **Automatic media setup** - Creates the media connection for you when a call arrives
- **Bidirectional audio streaming** - Send and receive raw PCM audio over the media connection
- **Buffer management** - Queue audio smoothly and clear pending playback on interruptions

## Recommended Flow

The public `0.24.0` API is built around a small set of core patterns:

1. Create a config with `TelcoflowClientConfig.sandbox(...)` or `TelcoflowClientConfig.production(...)`
2. Start the client with `async with TelcoflowClient(config) as client`
3. Register incoming-call handlers with `@client.on(events.INCOMING_CALL)`
4. Work with each `ActiveCall` using methods like `answer()`, `connect()`, `send_audio()`, `close()`, and `disconnect()`, noting that `close()` behaves differently before and after `connect()`

## Next Steps

- [Developer Onboarding](/introduction/developer-onboarding) - Gather the telco, phone number, WSS, firewall, and launch details needed before implementation
- [Installation](/introduction/installation) - Install the SDK and pin the version these docs describe
- [Quick Start](/introduction/quick-start) - Build a minimal `0.24.0` app
- [Architecture](/concepts/architecture) - Understand the control and media connection model