Skip to navigation
AssistantsModel configurations

Voice fallback configuration

Choose backup voices and troubleshoot failed fallback attempts

Overview

Voice fallback lets you configure an ordered list of backup voices. When a voice error triggers fallback, the assistant tries the next voice in your plan so the call can continue.

Built-in fallback behavior without a configured plan depends on the selected voice. Configure voice.fallbackPlan.voices to choose the backup voices and their order.

A fallback plan does not guarantee recovery from every voice error or provider outage. Some failures can end a call before a backup voice starts.

How it works

When a voice error triggers fallback, the assistant:

  1. Tries the first voice in voice.fallbackPlan.voices.
  2. Tries the next voice if a backup also fails and triggers fallback.
  3. May end the call if no voice succeeds.

Configure via Dashboard

1

Open the assistant

Open the Dashboard. Select Assistants, then select an assistant.

2

Open the fallback settings

Select the Voice card. Expand Advanced, then locate Fallback Voices.

3

Add a fallback voice

Select Add, then choose a Provider and Voice. To enter a voice ID instead, select Add Voice ID Manually.

4

Review the model

Review the selected Model, and choose another model if needed.

5

Configure provider-specific settings (optional)

Expand Additional Configuration, then configure the available settings. Review the provider-specific settings for details about each option.

6

Add more fallbacks

Select Add to configure another fallback voice. Vapi attempts fallback voices in the order they are listed.

Configure via API

Add the fallbackPlan property to your assistant’s voice configuration, and specify the fallback voices within the voices property.

Fallback voices must be valid JSON configurations, not strings. The order matters—Vapi will choose fallback voices starting from the beginning of the list.

{
  "voice": {
    "provider": "openai",
    "voiceId": "shimmer",
    "fallbackPlan": {
      "voices": [
        {
          "provider": "cartesia",
          "voiceId": "248be419-c632-4f23-adf1-5324ed7dbf1d"
        },
        {
          "provider": "11labs",
          "voiceId": "cgSgspJ2msm6clMCkdW9",
          "stability": 0.5,
          "similarityBoost": 0.75
        }
      ]
    }
  }
}

Troubleshoot voice fallback

If a call ends instead of switching to a backup voice:

1

Inspect the call logs

Open call logs and check the endedReason and voice errors. If detailed pipeline logs are available, look for a fallback attempt. Some provider connection failures can end the call before fallback starts.

2

Check the fallback plan

Confirm that the assistant or call configuration used for the call includes voice.fallbackPlan.voices. Check the order of the backup voices and verify each voice ID, model, and required provider credentials.

3

Test the backup as the primary voice

Make a test call with a known working backup voice as the primary voice. If it produces audio, use that provider as the primary voice for new calls. Then investigate why the original provider did not switch.

4

Share a failing call with support

If the test call still fails or fallback does not start, share the call ID, endedReason, and primary and backup providers with Vapi support.

A test call with an invalid primary voice ID can check whether the plan handles that configuration error. It does not verify fallback during a provider outage.

Provider-specific settings

Each voice provider supports different configuration options. Expand the accordion below to see available settings for each provider.

  • speed (0.5-2): Speech rate multiplier. Default is 1.0.
  • model: Select from sonic-3.5, sonic-3.5-2026-05-04, sonic-3, or sonic-3-2026-01-12.
  • language: Language code for the voice.
  • experimentalControls.speed: Speech speed adjustment (-1 to 1). Negative values slow down; positive values speed up.
  • experimentalControls.emotion: Array of emotion configurations (e.g., ["happiness:high", "curiosity:medium"]).
  • generationConfig (sonic-3 only):
    • speed (0.6-1.5): Fine-grained speed control.
    • volume (0.5-2.0): Volume adjustment.
    • experimental.accentLocalization (0 or 1): Toggle accent localization.
  • model: Select from aura or aura-2. Defaults to aura-2.
  • mipOptOut (boolean): Opt out of the Deepgram Model Improvement Partnership program.
  • stability (0-1): Controls voice consistency. Lower values allow more emotional range; higher values produce more stable output.
  • similarityBoost (0-1): Enhances similarity to the original voice. Higher values make the voice more similar to the reference.
  • style (0-1): Voice style intensity. Higher values amplify the speaker’s style.
  • useSpeakerBoost (boolean): Enable to boost similarity to the original speaker.
  • speed (0.7-1.2): Speech speed multiplier. Default is 1.0.
  • optimizeStreamingLatency (0-4): Controls streaming latency optimization. Default is 3.
  • enableSsmlParsing (boolean): Enable SSML pronunciation support.
  • model: Select from eleven_flash_v2, eleven_flash_v2_5, eleven_multilingual_v2, or eleven_v3.
  • model: Model selection (e.g., octave2).
  • description: Natural language instructions describing how the speech should sound (tone, intonation, pacing, accent).
  • isCustomHumeVoice (boolean): Indicates whether using a custom Hume voice.
  • speed (0.25-2): Speech rate multiplier. Default is 1.0.
  • language: Two-letter ISO 639-1 language code, or auto for auto-detection.
  • model: Select from speech-02-hd, speech-02-turbo, or speech-2.5-turbo-preview. Defaults to speech-02-turbo.
  • emotion: Emotion preset (happy, sad, angry, fearful, surprised, disgusted, neutral).
  • pitch (-12 to 12): Voice pitch adjustment in semitones.
  • speed (0.5-2): Speech speed adjustment.
  • volume (0.5-2): Volume adjustment.
  • model: Model selection (e.g., neu_fast).
  • language: Language code (required).
  • speed (0.25-2): Speech speed multiplier.
  • speed (0.25-4): Speech speed multiplier. Default is 1.0.
  • model: Select from tts-1, tts-1-hd, or gpt-4o-mini-tts.
  • instructions: Voice prompt to control the generated audio style. Does not work with tts-1 or tts-1-hd models.
  • speed (0.1-5): Speech rate multiplier.
  • temperature (0.1-2): Controls voice variance. Lower values are more predictable; higher values allow more variation.
  • emotion: Emotion preset (e.g., female_happy, male_sad, female_angry, male_surprised).
  • voiceGuidance (1-6): Controls voice uniqueness. Lower values reduce uniqueness.
  • styleGuidance (1-30): Controls emotion intensity. Higher values create more emotional performance.
  • textGuidance (1-2): Controls text adherence. Higher values are more accurate to input text.
  • model: Select from PlayHT2.0, PlayHT2.0-turbo, Play3.0-mini, or PlayDialog.
  • model: Select from arcana, mistv2, or mist. Defaults to arcana.
  • speed (0.1+): Speech speed multiplier.
  • pauseBetweenBrackets (boolean): Enable pause control using angle brackets (e.g., <200> for 200ms pause).
  • phonemizeBetweenBrackets (boolean): Enable phonemization using curly brackets (e.g., {h'El.o}).
  • reduceLatency (boolean): Optimize for reduced streaming latency.
  • inlineSpeedAlpha: Inline speed control using alpha notation.
  • model: Model selection (e.g., lightning).
  • speed: Speech speed multiplier.
  • model: Model selection.
  • enableSsml (boolean): Enable limited SSML translation for input text.
  • libraryIds: Array of library IDs to use for voice synthesis.

Best practices

  • Use different providers for your fallback voices to reduce the impact of a provider outage.
  • Select voices with similar characteristics (tone, accent, gender) to maintain consistency in the user experience.
  • Test the providers in your fallback configuration together to ensure smooth transitions between voices.

FAQ

There is no change to the pricing of the voices. Your call will not incur any extra fees while using fallback voices, and you will be able to see the cost for each voice in your end-of-call report. To review a call’s costs, see Call Cost in call logs.

You can configure as many fallback voices as you need. However, we recommend 2-3 fallbacks from different providers for optimal reliability.

Users may notice a brief pause and a change in voice characteristics when switching to a fallback voice. Selecting voices with similar properties helps minimize this disruption.