Skip to main content
Start with Your first voice agent for a working conversation. This page is the reference for changing providers and resolving configuration after the basic lessons. Set Agent(voice_config=...) to configure sessions created by the server. Use a sparse dict or VoiceConfig so the fields you omit inherit operator defaults. The server applies environment defaults, then the agent’s declared settings, then allowed per-call client overrides. The client cannot supply credentials, arbitrary provider hosts, recording paths, or Python detector objects.

Transcription providers

Set stt_provider and optionally stt_model. These are adapter IDs and speech model IDs, separate from the provider/model IDs used by Agent.model.
  • deepgram or deepgram-flux (default): defaults to flux-general-multi; requires DEEPGRAM_API_KEY. Flux reports native end-of-turn events, so the session uses provider turn detection. When DEEPGRAM_API_KEY is unset, each session falls back to elevenlabs.
  • elevenlabs: defaults to scribe_v2_realtime; requires ELEVENLABS_API_KEY.
  • deepgram-nova: defaults to nova-3; requires DEEPGRAM_API_KEY. Select Nova explicitly or supply a nova-* model.
  • munsit: defaults to munsit-en-ar; requires MUNSIT_API_KEY. Reports native utterance boundaries.
  • openai: defaults to gpt-transcribe; requires OPENAI_API_KEY. Uses a transcription-only Realtime session with server VAD. It does not report native end-of-turn, so the session uses local turn detection when timbal[voice] is installed and lexical detection otherwise. Flux and Munsit are the adapters that force provider mode.
Set language to a provider-supported language hint or omit it for automatic detection. Provider-specific transcription options belong in stt_extra. Each adapter supports its own options; switching providers does not make an option portable.

Speech providers

Set tts_provider, tts_model, and voice for the output provider:
  • elevenlabs (default): defaults to eleven_v4_turbo; requires ELEVENLABS_API_KEY and an accessible ElevenLabs voice ID. Supports incremental text through one streaming context per reply. Set tts_model to eleven_flash_v2_5 for the previous default.
  • deepgram: defaults to aura-2-thalia-en; requires DEEPGRAM_API_KEY. The full Aura model ID identifies the voice and language.
  • fishaudio: defaults to s2.1-pro; requires FISH_API_KEY. Use a Fish reference voice ID for voice when selecting a reference voice.
  • munsit: defaults to faseeh-v1-preview; requires MUNSIT_API_KEY. The fallback voice is MUNSIT_VOICE_ID or ar-uae-male-1.
  • openai: defaults to gpt-4o-mini-tts and coral; requires OPENAI_API_KEY. Synthesizes complete text segments as they become ready.
Use the chosen provider’s voice ID. language controls transcription; it does not select a Deepgram Aura voice. Output style options belong in tts_extra. See Speech examples for detailed OpenAI and Deepgram settings. The default session audio is mono PCM16 little-endian at 16,000 Hz (sample_rate=16000, encoding="pcm_s16le"). Transports convert their wire formats where needed. OpenAI uses 24 kHz on the provider connection and requires the voice extra to resample other session rates. stt_extra defaults to ElevenLabs-oriented VAD keys (commit_strategy, min_speech_duration_ms, vad_silence_threshold_secs, vad_threshold). The server strips those keys for adapters that own end-of-turn. tts_extra defaults to {"auto_mode": true}. VoiceConfig.model is a per-session text-model override (provider/model), separate from stt_model and tts_model.

What a client may override

A browser or phone hello may set stt_provider, stt_model, tts_provider, tts_model, voice, language, sample_rate, encoding, stt_extra, tts_extra, vad_endpointing, model, tool_beat_secs, turn_timeout_secs, turn_timeout_fallback, filler, greeting, outbound_greeting, and user_idle. It may also send transport keys turn_detector (a mode name), parent_id (continue a text run), direction, and call_context. call_context is ignored unless the server sets TIMBAL_VOICE_ALLOW_CLIENT_CALL_CONTEXT=1. Recording, ambient audio, events, hello_wait_secs, and sip_hello_wait_secs are server-only. Unknown VoiceConfig keys fail at startup (extra is forbidden). Empty optional blocks (greeting, filler, user_idle, ambient, recording, events) are treated as unset so they do not wipe an inherited value.

Mix providers

With OPENAI_API_KEY configured, this selects OpenAI for transcription and speech while keeping agent.model as the conversation model:
This assignment replaces the agent’s declared config. Keep any greetings or other behavior fields you want to retain. The earlier lessons use a dict and add individual keys to preserve previous behavior; a VoiceConfig instance or callable needs its own update pattern.

Turn detection

See Turn-taking and interruptions for mode names, native provider boundaries, VAD endpointing, and a listening test.

Greetings and silence

See Greetings for fixed and generated openers, timing, and outbound behavior. Silence and timeouts covers idle prompts, hangup, and the voice turn deadline.

Tool-call fillers

See Spoken fillers to enable a waiting phrase, tune generation, or repeat it during a long tool call. Thinking sounds are a separate browser feature.

Operator defaults

The server reads TIMBAL_STT_PROVIDER, TIMBAL_STT_MODEL, TIMBAL_TTS_MODEL, ELEVENLABS_VOICE_ID (before TIMBAL_VOICE_ID), TIMBAL_VOICE_LANGUAGE, and TIMBAL_VOICE_GREETING. TIMBAL_VOICE_ID alone also sets the default ElevenLabs voice. Use voice_config.tts_provider to select the output provider; there is no TIMBAL_TTS_PROVIDER reader in the server. An unknown STT or TTS provider id falls back to ElevenLabs for that session rather than refusing to boot. TIMBAL_VOICE_FILLER=1 enables default fillers. The TIMBAL_VOICE_FILLER_MODEL, TIMBAL_VOICE_FILLER_SYSTEM_PROMPT, TIMBAL_VOICE_FILLER_DELAY_SECS, TIMBAL_VOICE_FILLER_REPEAT_SECS, and TIMBAL_VOICE_FILLER_THINK_DELAY_SECS variables customize them. See Recording calls and Background audio for their operator settings and transport limits.