voice.calls / voice.agents) that originates, transfers,
hangs up, and binds server-side agents over the control-plane API, and a
data plane (voice.audio_bridge) that streams call audio in and out over our
QUIC/MoQT transport. Reach for it when the call driver lives on a server —
an outbound dialer, an agent supervisor, a “tap the audio to my own ASR”
pipeline — rather than in a browser.
The control plane is pure Python (standard-library HTTP, no native
dependency). The data plane (
voice.audio_bridge) rides our QUIC/MoQT
transport through a shared native library, so publishing or subscribing to
audio needs the MoQT FFI available at runtime (see Install).
The SDK is synchronous and blocking — it does not use asyncio; uplink
frames arrive on a callback you register.Install and authenticate
Provide the audio transport library (data plane only)
Originating and controlling calls works with the package alone. To stream
audio through
voice.audio_bridge, point the SDK at the native MoQT
transport library and export your API key:Voice(...)
Top-level client. All constructor arguments are keyword-only.
Control-plane API base URL for your workspace — e.g.
https://engine.telequick.dev.Voice API key (sent as a bearer token). Keep it server-side.
Your workspace / organization id. Scopes every request.
MoQT relay host the audio bridge dials for the data plane. Override only for
self-hosted / on-prem deployments.
| Attribute | Type | Plane |
|---|---|---|
v.calls | Calls | control — originate / get / transfer / hangup |
v.audio_bridge | AudioBridgeFactory | data — attach and stream audio |
v.agents | Agents | control — bind a server-side agent to a call |
VoiceError (importable from telequick.voice) on a
bad argument or a non-2xx control-plane response.
Originate and control calls
v.calls.originate(...)
Places an outbound call against a trunk and returns a Call. Arguments are
keyword-only.
Destination in E.164, e.g.
"+15551234567".Caller-ID in E.164. (Named
from_ because from is a Python keyword; it is
sent as from on the wire.)The SIP trunk to originate on. See
SIP trunking.
If set, the engine binds this server-side agent and wires the audio bridge
end-to-end — you do not need to open an
AudioBridge yourself.Seconds to ring before giving up.
The Call object
originate and get return a Call. Its sid is the universal key — the same
call_sid names the SIP dialog, the media session, the agent session, the MoQT
namespace, and the CDR.
Call identifier (
call_sid).One of
dialing, ringing, in_progress, completed, failed, no_answer.Destination E.164.
Caller-ID E.164.
Originating trunk.
Bound agent, if any.
v.agents.attach(call_sid, agent)
Bind a running server-side agent to an existing call. The engine wires the audio
bridge for you — use this when the call already exists (e.g. inbound) and you
want the agent runtime to take the audio.
Bridge call audio
voice.audio_bridge.attach(...) opens a bidirectional audio bridge for one call.
It subscribes to the caller’s uplink (voice/<sid>/uplink) and delivers each
frame to your on_uplink callback, and it publishes your downlink
(voice/<sid>/downlink) back toward the caller via bridge.publish_downlink(...).
This is the server / agent side of the bridge — you receive caller audio and send
audio to the caller.
The
call.sid to bridge.Called for every caller frame with
(frame_bytes, timestamp_us). Runs on the
transport’s delivery thread — keep it fast and hand off heavy work.Wire codec for the downlink you publish. See Codecs.
Sample rate of the audio you publish (48 kHz for Opus).
Channel count (mono).
Frame duration in ms.
AudioBridge.publish_downlink(frame, *, timestamp_us=None) sends one frame
toward the caller; if you omit timestamp_us the SDK stamps it from a monotonic
clock. Hold the AudioBridge reference for the call’s lifetime — letting it be
collected closes the session.
The Python data plane today ships the server/agent-side attach only
(subscribe uplink, publish downlink). The caller-side helpers exposed by the
TypeScript SDK —
attachCaller, publishUplink, onDownlink — are not yet
part of the Python surface. If you need to originate audio as the caller
from Python (e.g. a synthetic caller), use the
TypeScript SDK for now.Codecs and audio format
codec accepts "opus" | "pcm16" | "g711_ulaw" | "g711_alaw". Voice is
audio-only — there are no video codecs. Phone legs are G.711 (µ-law / A-law) on
the wire; browser and app legs are Opus (48 kHz mono, 20 ms frames). The engine
transcodes to and from its internal PCM representation, so you publish and
receive in the codec you pass to attach. For the full track / namespace model
see
Sessions, calls, tracks & streams.
Full example: originate, attach, tap
Originate a call, let a server-side agent run the ASR/LLM/TTS loop, and tap the uplink in parallel to write a transcript-friendly frame log.This mirrors the
voice_agent_attach.py example shipped with the SDK. Because
the SDK is blocking, run long-lived taps under a thread or process you control
and drive shutdown from a signal, as above.Related
TypeScript SDK
The primary SDK, including the caller-side audio surface.
Agent control events
The human-agent control channel and its event model.
Calls API
The control-plane call routes the SDK wraps.
Outbound call cookbook
An end-to-end outbound walkthrough.
Stream to your ASR
Tap the uplink into your own speech pipeline.
Agent runtime
What a bound server-side agent does with the audio.