API Reference | Telcoflow SDK

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

1 sandbox_config = TelcoflowClientConfig.sandbox(
2     api_key="YOUR_API_KEY",
3     connector_uuid="YOUR_CONNECTOR_UUID",
4     sample_rate=24000,
5 )
6 
7 production_config = TelcoflowClientConfig.production(
8     cert_path="/etc/certs/client.pem",
9     key_path="/etc/certs/client.key",
10     sample_rate=24000,
11 )

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

1 async with TelcoflowClient(config) as client:
2     @client.on(events.INCOMING_CALL)
3     async def on_call(call):
4         await call.answer()
5 
6     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:

1 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 - See how these methods map to the call lifecycle
Error Handling - Review the exception hierarchy and recovery patterns
Advanced Topics - Logging, concurrency, and operational notes