Skip to content

Configuration

Constructor

from voxbridge import VoiceClient

client = VoiceClient(
    provider="retell",
    api_key="key_...",
    webhook_secret="key_...",   # optional
    webhook_max_age=300,        # Retell only, optional
    timeout=30,                 # optional
)
Argument Default Meaning
provider required "vapi" or "retell"; anything else raises ValueError.
api_key required The provider API key, sent as Authorization: Bearer.
webhook_secret none Secret used to verify webhooks. On Vapi, leaving it unset means webhooks are not verified. On Retell it falls back to the API key.
webhook_max_age 300 (Retell) Retell only. Maximum age of a webhook signature in seconds; None disables the replay check. Passing it for Vapi raises NotSupported, because Vapi signatures carry no timestamp.
timeout 30 Per-request HTTP timeout in seconds.

From the environment

VoiceClient.from_env() reads:

Variable Used for
VOICE_PROVIDER Provider name (skipped if you pass provider=).
VAPI_API_KEY / RETELL_API_KEY api_key. Required unless you pass api_key=.
VAPI_WEBHOOK_SECRET / RETELL_WEBHOOK_SECRET webhook_secret.
RETELL_WEBHOOK_MAX_AGE webhook_max_age, a number. Setting VAPI_WEBHOOK_MAX_AGE raises NotSupported.

Empty values count as unset. A missing provider or key, an unknown provider, or a non-numeric max age raises ValueError with a message naming the variable.

VoiceClient.from_env()                       # provider from VOICE_PROVIDER
VoiceClient.from_env("vapi")                 # explicit provider
VoiceClient.from_env("retell", timeout=60)   # keyword overrides win over the environment
VoiceClient.from_env("vapi", api_key=key)    # key from elsewhere; VAPI_API_KEY not needed
VoiceClient.from_env(environ={"VOICE_PROVIDER": "vapi", "VAPI_API_KEY": "sk-..."})  # custom mapping

Where the variables come from

voxbridge reads os.environ and nothing else; it does not load .env files. Either export the variables in your shell or deployment platform, or load a .env yourself before building the client with python-dotenv:

from dotenv import load_dotenv

from voxbridge import VoiceClient

load_dotenv()                  # copies .env entries into os.environ
client = VoiceClient.from_env()

python-dotenv is not a voxbridge dependency; install it yourself (pip install python-dotenv). Keep .env out of version control.

Retell webhook key

Retell signs webhooks with an API key that carries the webhook badge in the Retell dashboard. When you don't pass a webhook_secret, voxbridge verifies with api_key, which only works if that key is the badged one. If your API key is not badged, pass the badged key as webhook_secret (or set RETELL_WEBHOOK_SECRET).