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 |
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; |
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 |
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 |
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
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.