Skip to content

Quickstart

Create a client

Set the provider and its key in the environment and build the client from it:

export VOICE_PROVIDER=vapi        # or retell
export VAPI_API_KEY=...           # or RETELL_API_KEY
from voxbridge import VoiceClient

client = VoiceClient.from_env()

The explicit form takes the same options (see Configuration):

client = VoiceClient(provider="vapi", api_key="sk-...")  # or provider="retell"

Unknown provider names raise ValueError. The client is a context manager and close() runs on exit:

with VoiceClient.from_env() as client:
    ...

Create an agent

from voxbridge import Agent, Tool

agent = client.create_agent(Agent(
    name="Scheduler",
    system_prompt="You are a friendly scheduling assistant.",
    model="gpt-4o",
    voice="elevenlabs:rachel",       # "<tts-provider>:<voiceId>"
    first_message="Hi, this is Scheduler. How can I help?",
    tools=[Tool(
        name="book_appointment",
        description="Book an appointment slot",
        parameters={"type": "object", "properties": {"day": {"type": "string"}}},
        endpoint_url="https://example.com/tools/book",
    )],
))
print(agent.id)          # provider-assigned id
print(agent.raw)         # the untouched provider payload

The same Agent works on either provider; voxbridge maps the prompt, voice and tools into each provider's native shape. Voice ids are "<tts-provider>:<voiceId>" (elevenlabs is normalized to 11labs), but the voice catalogs differ between providers, so check the voice exists on the one you use. Retell stores the prompt on a separate LLM object, so create_agent makes two API calls there; see Providers for what that means for updates and failures.

Place a call

call = client.create_call(agent.id, "+15550000000", from_number="+15550000001")
call = client.get_call(call.id)
print(call.status, call.transcript)

for c in client.list_calls(limit=20):
    print(c.id, c.status)

Outbound calls need a caller number (from_number) on both providers. Retell raises ValueError without it. On Vapi, pass an E.164 number, looked up among your phone numbers (ProviderError if none matches), or a phone-number id.

Handle a webhook

parse_webhook verifies the request and normalizes it to a WebhookEvent. Pass the raw body bytes, not re-serialized JSON:

from voxbridge import CallEnded, ToolCall, TranscriptChunk

event = client.parse_webhook(request.headers, raw_body)
match event:
    case CallEnded(call_id=cid, transcript=t, ended_reason=r):
        ...
    case TranscriptChunk(role=role, text=text):
        ...
    case ToolCall(name=name, arguments=args):
        reply = client.tool_response(event, {"ok": True})  # return as the HTTP 200 JSON body

A failed verification raises SignatureError; a malformed body raises ProviderError. Verification rules differ per provider (Vapi accepts unsigned requests unless you set a secret), so read Webhooks & tools before going to production. A runnable FastAPI server is in examples/fastapi_server.py.

Async

Every agent/call method has an a-prefixed async twin with the same signature (parse_webhook, verify_signature and tool_response are sync):

async with VoiceClient.from_env() as client:
    agent = await client.acreate_agent(Agent(
        name="Scheduler", system_prompt="Be brief.", model="gpt-4o", voice="openai:alloy",
    ))
    call = await client.aget_call("call_123")
    calls = await client.alist_calls()

parse_webhook, verify_signature and tool_response stay synchronous; they do no I/O.

Handle errors

from voxbridge import AuthError, NotSupported, ProviderError, RateLimited

try:
    client.get_call("call_123")
except RateLimited as exc:
    print("retry in", exc.retry_after)
except AuthError:
    print("check your API key")
except ProviderError as exc:
    print(exc.status_code, exc.body)
except NotSupported as exc:
    print("not available on this provider:", exc)

AuthError and RateLimited subclass ProviderError, so catch them first. Each request is retried at most once; see the API reference for the exact policy.