Skip to content

API reference

Client

Provider-agnostic entry point: same API regardless of backend.

Requests are retried at most once. Connect errors, connect timeouts and 429 responses are retried for any request; read/write timeouts, 500/502/503/504 responses and other request errors only for idempotent requests. A Retry-After header is honoured, capped at 10 seconds. Capabilities a provider lacks raise NotSupported.

__init__(provider, api_key, *, webhook_secret=None, webhook_max_age=_UNSET, timeout=30.0)

Create a client for one provider.

Parameters:

Name Type Description Default
provider str

Provider name, "vapi" or "retell".

required
api_key str

The provider API key.

required
webhook_secret str | None

Secret used to verify webhooks. Retell falls back to the API key when omitted.

None
webhook_max_age float | None | _Unset

Retell only. Max webhook signature age in seconds (default 300); None disables the replay check.

_UNSET
timeout float

Per-request HTTP timeout in seconds.

30.0

Raises:

Type Description
ValueError

If the provider name is unknown.

NotSupported

If webhook_max_age is passed for Vapi.

from_env(provider=None, *, environ=None, **overrides) classmethod

Build a client from environment variables.

Reads VOICE_PROVIDER (unless provider is given), then

_API_KEY,

_WEBHOOK_SECRET and

_WEBHOOK_MAX_AGE where

is the upper-cased provider name. Empty values count as unset.

Parameters:

Name Type Description Default
provider str | None

Provider name; defaults to VOICE_PROVIDER.

None
environ Mapping[str, str] | None

Mapping to read instead of os.environ.

None
**overrides Any

Keyword arguments for the constructor (api_key, webhook_secret, webhook_max_age, timeout); they win over environment values. With an api_key override,

_API_KEY is not required.

{}

Raises:

Type Description
ValueError

If the provider or API key is missing, or

_WEBHOOK_MAX_AGE is not a number.

NotSupported

If

_WEBHOOK_MAX_AGE is set for Vapi.

create_agent(agent)

Create an agent on the provider and return it with its id.

update_agent(agent_id, agent)

Update an existing agent from the given definition and return it.

get_agent(agent_id)

Fetch an agent by id.

delete_agent(agent_id)

Delete an agent by id.

create_call(agent_id, to_number, *, from_number=None)

Start an outbound call.

Parameters:

Name Type Description Default
agent_id str

The agent that will handle the call.

required
to_number str

Destination number in E.164 format.

required
from_number str | None

Caller number; needed for outbound calls on both providers. Retell requires an E.164 number (ValueError if missing). On Vapi pass an E.164 number, looked up among your phone numbers, or a phone-number id.

None

Raises:

Type Description
ValueError

On Retell, if from_number is missing.

ProviderError

On Vapi, if no phone number matches from_number.

get_call(call_id)

Fetch a call by id.

list_calls(*, limit=None)

List calls.

Parameters:

Name Type Description Default
limit int | None

Maximum number of calls to return; None uses the provider default.

None

parse_webhook(headers, raw_body)

Verify a webhook request and parse it into an event.

Parameters:

Name Type Description Default
headers Mapping[str, str]

The request headers.

required
raw_body bytes

The unmodified request body bytes.

required

Raises:

Type Description
SignatureError

If verification fails.

ProviderError

If the body is not JSON or not a webhook of the expected shape.

verify_signature(headers, raw_body)

Return True if the webhook request is authentic, without parsing it.

tool_response(event, result)

Build the HTTP response body to return for a tool call.

Parameters:

Name Type Description Default
event ToolCall

The ToolCall event parsed from the webhook.

required
result Any

The tool's result; must be JSON-serialisable.

required

close()

Close the provider's sync HTTP client.

acreate_agent(agent) async

Async twin of create_agent.

aupdate_agent(agent_id, agent) async

Async twin of update_agent.

aget_agent(agent_id) async

Async twin of get_agent.

adelete_agent(agent_id) async

Async twin of delete_agent.

acreate_call(agent_id, to_number, *, from_number=None) async

Async twin of create_call.

aget_call(call_id) async

Async twin of get_call.

alist_calls(*, limit=None) async

Async twin of list_calls.

aclose() async

Close the provider's async HTTP client.

Models

Tool

Bases: BaseModel

A function the voice agent can call during a conversation.

Attributes:

Name Type Description
name str

Function name the model uses to invoke the tool.

description str

What the tool does, shown to the model.

parameters dict[str, Any]

JSON Schema describing the tool's arguments.

endpoint_url str | None

Server URL the provider calls when the tool is invoked, if any.

Agent

Bases: BaseModel

A provider-neutral voice agent definition.

Attributes:

Name Type Description
name str

Display name of the agent.

system_prompt str

Instructions that define the agent's behaviour.

model str

LLM model identifier, for example gpt-4o.

voice str

Voice identifier on the provider.

first_message str | None

What the agent says when a call connects, if anything.

tools list[Tool]

Tools the agent may call.

id str | None

Provider-assigned agent id; None until the agent is created.

raw dict[str, Any]

Unmodified provider payload this agent was built from.

Call

Bases: BaseModel

A phone call placed through a provider.

Attributes:

Name Type Description
id str | None

Provider-assigned call id.

agent_id str | None

Id of the agent handling the call.

status str | None

Provider-reported call status, for example ended.

to_number str | None

Number that was dialled, in E.164 format.

from_number str | None

Number the call came from, in E.164 format.

transcript str | None

Full transcript, once the provider has one.

raw dict[str, Any]

Unmodified provider payload this call was built from.

Events

CallStarted

Bases: _Base

A call has connected.

CallEnded

Bases: _Base

A call has finished.

Attributes:

Name Type Description
transcript str | None

Full call transcript, if the provider included one.

ended_reason str | None

Provider-reported reason the call ended.

TranscriptChunk

Bases: _Base

A piece of live transcript.

Attributes:

Name Type Description
role str | None

Speaker, for example user or assistant.

text str

The transcribed text.

ToolCall

Bases: _Base

The agent wants your server to run a tool.

Answer it with VoiceClient.tool_response.

Attributes:

Name Type Description
name str

Name of the tool to run.

arguments dict[str, Any]

Arguments the model supplied.

tool_call_id str | None

Provider id to echo back in the response, if the provider uses one.

ErrorEvent

Bases: _Base

The provider reported an error.

Attributes:

Name Type Description
message str

Error description from the provider.

Errors

VoxBridgeError

Bases: Exception

Base for all voxbridge errors.

ProviderError

Bases: VoxBridgeError

A provider call failed or returned something unusable.

Attributes:

Name Type Description
status_code

HTTP status code, if the failure was an HTTP response.

provider

Name of the provider involved.

body

Decoded response body, if any.

AuthError

Bases: ProviderError

401/403 from a provider.

RateLimited

Bases: ProviderError

429 from a provider.

Attributes:

Name Type Description
retry_after

Seconds the provider asked you to wait, if it said.

NotSupported

Bases: VoxBridgeError

Requested capability is not available on the selected provider.

SignatureError

Bases: VoxBridgeError

Webhook signature verification failed.