diff --git a/fern/calls/call-ended-reason.mdx b/fern/calls/call-ended-reason.mdx index 4f9e3f793..4a731231d 100644 --- a/fern/calls/call-ended-reason.mdx +++ b/fern/calls/call-ended-reason.mdx @@ -20,7 +20,7 @@ Start here if a call failed and you want to quickly understand what happened: | Phone never rang | `call.start.error-*`, `assistant-not-found`, `*-transport-never-connected` | Account/billing issue, bad configuration, or Vapi infrastructure error | | Phone rang but no answer | `customer-did-not-answer`, `customer-busy`, SIP 408/480 | Normal behavior — callee was unavailable | | Call dropped mid-conversation | `*-worker-died`, `phone-call-provider-closed-websocket`, `worker-shutdown` | Network issue or Vapi infrastructure error (usually transient) | -| Assistant went silent or unresponsive | `*-llm-failed`, `*-voice-failed`, `*-transcriber-failed`, `*-429-*`, `*-500-*` | Provider outage or credential/quota issue — configure fallback providers for the 3 core services (TTS, LLM, STT) | +| Assistant went silent or unresponsive | `*-llm-failed`, `*-voice-failed`, `*-transcriber-failed`, `*-429-*`, `*-500-*` | Provider error or credential/quota issue — configure fallback for the affected service, then inspect call logs and test the backup provider | | Call worked normally, then ended | `assistant-ended-call`, `customer-ended-call`, `silence-timed-out`, `exceeded-max-duration` | Expected behavior — adjust timeout settings if calls end too early | | Transfer failed | `*-transfer-failed`, `*-warm-transfer-*`, SIP 403/503 | Bad transfer destination or SIP configuration | diff --git a/fern/calls/troubleshoot-call-errors.mdx b/fern/calls/troubleshoot-call-errors.mdx index 8dac72040..a3918bea6 100644 --- a/fern/calls/troubleshoot-call-errors.mdx +++ b/fern/calls/troubleshoot-call-errors.mdx @@ -203,9 +203,11 @@ If you've configured **fallback providers**, some transcriber and voice errors w - -To prevent provider outages from killing your calls, configure fallback providers for your transcriber, voice, and model. Non-fatal errors will trigger a provider swap instead of ending the call. - + +Configured fallback providers can keep some provider errors from ending a call. Voice fallback may not activate for every provider failure. + + +If a voice error ends the call, follow [Troubleshoot voice fallback](/voice-fallback-plan#troubleshoot-voice-fallback). Test a working backup provider as the primary voice. ## Transfer failed diff --git a/fern/customization/custom-tts.mdx b/fern/customization/custom-tts.mdx index b2ef0b6c1..bcbee6767 100644 --- a/fern/customization/custom-tts.mdx +++ b/fern/customization/custom-tts.mdx @@ -548,6 +548,5 @@ Now that you have custom TTS integration working: - **Multi-language support:** Add language detection and voice switching -Consider implementing a fallback voice provider in your assistant configuration to ensure call continuity if your custom TTS endpoint experiences issues. +Configure and test a backup voice for your custom TTS endpoint. If the call ends before fallback starts, follow [Troubleshoot voice fallback](/voice-fallback-plan#troubleshoot-voice-fallback) and try the backup as the primary voice. -``` diff --git a/fern/customization/model-fallback-plan.mdx b/fern/customization/model-fallback-plan.mdx new file mode 100644 index 000000000..20bedbe1f --- /dev/null +++ b/fern/customization/model-fallback-plan.mdx @@ -0,0 +1,97 @@ +--- +title: Model fallback configuration +subtitle: Configure a backup language model that activates automatically if your primary model fails +description: Configure fallbackModels in Vapi so a backup language model takes over automatically when your primary LLM fails. Covers which providers currently support model fallback and how it differs from voice and transcriber fallback. +slug: customization/model-fallback-plan +--- + +## Overview + +Model fallback lets a backup language model take over automatically if your primary model fails, so the call keeps going instead of ending in an error. + + + Model fallback is currently supported for the [OpenAI](/providers/model/openai) and [Anthropic Bedrock](/providers/model/anthropic-bedrock) providers only. It is not yet a cross-provider fallback like [voice fallback](/voice-fallback-plan) or [transcriber fallback](/customization/transcriber-fallback-plan), which can fall back to a different provider entirely. Without `fallbackModels` configured, your call ends with an error if your chosen model provider fails. + + +## How it works + +When a model failure occurs, Vapi will: + +1. Detect the failure of the primary model. +2. If `fallbackModels` is configured, switch to the first fallback model in the list. +3. For OpenAI, continue through the rest of your specified list if subsequent failures occur. For Anthropic Bedrock, only one fallback model can be configured, so Vapi tries that single model. +4. Terminate the call only if every configured fallback has also failed. + +Fallback models stay on the same provider as your primary model. To protect against a provider-wide outage, pair model fallback with [voice fallback](/voice-fallback-plan) and [transcriber fallback](/customization/transcriber-fallback-plan) on the other two pipeline components, which do support cross-provider fallback. + +## Configure via API + +Add `fallbackModels` directly to your assistant's `model` object. There is no separate `fallbackPlan` wrapper for models — unlike `voice.fallbackPlan.voices` and `transcriber.fallbackPlan.transcribers`, `fallbackModels` is a sibling property of `model.model` itself. + +### OpenAI + +Set `model.fallbackModels` to an ordered list of OpenAI model IDs. Vapi tries them in order if the primary model fails. + +```json +{ + "model": { + "provider": "openai", + "model": "gpt-5.5", + "fallbackModels": ["gpt-5.4", "gpt-4.1"] + } +} +``` + + + You shouldn't need to set this unless you have a specific reason to — Vapi automatically finds the fastest fallback models that make sense for your primary model. + + +### Anthropic Bedrock + +Set `model.fallbackModels` to at most one same-provider Claude model ID available through Bedrock. + +```json +{ + "model": { + "provider": "anthropic-bedrock", + "model": "claude-sonnet-4-6", + "fallbackModels": "claude-haiku-4-5-20251001" + } +} +``` + + + The fallback model is resolved using the call's Bedrock credential region (or `ANTHROPIC_BEDROCK_AWS_REGION`). A fallback name with no inference profile in that region is skipped and a warning is logged — Vapi never silently remaps it to a US or global profile. On Vapi EU, a fallback name without an EU inference profile is rejected at write time. `fallbackModels` cannot be combined with `thinking` in this release. + + +## Other providers + +Vapi's other language model providers — including [Anthropic](/providers/model/anthropic) (non-Bedrock), [Google](/providers/model/gemini), [Groq](/providers/model/groq), [xAI](/providers/model/xai), [Mistral](/providers/model/mistral), [MiniMax](/providers/model/minimax), and [Custom LLM](/customization/custom-llm/fine-tuned-openai-models) — do not currently expose a `fallbackModels` field. If your primary model is on one of these providers and it fails, the call ends with an error unless you handle retries at the application layer. + +## FAQ + + + + Not yet. `fallbackModels` only lets you specify backup models from the same provider as your primary model. Cross-provider model fallback isn't currently supported — use [voice fallback](/voice-fallback-plan) and [transcriber fallback](/customization/transcriber-fallback-plan) to protect those two pipeline components against a provider-wide outage. + + + You're billed normally for whichever model actually generates the response, whether that's your primary model or a fallback. + + + `fallbackModels` is currently only available on `OpenAIModel` and `AnthropicBedrockModel`. It isn't exposed for other providers yet. + + + +## Related + +#### [Voice fallback configuration](/voice-fallback-plan) + +Configure fallback voices that activate automatically when your primary voice provider fails. + +#### [Transcriber fallback configuration](/customization/transcriber-fallback-plan) + +Configure fallback transcribers so calls keep working if your primary speech-to-text provider fails. + +#### [Model providers](/providers/model/overview) + +Compare every language model provider Vapi supports. diff --git a/fern/docs.yml b/fern/docs.yml index 34520d9e6..cff559889 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -1,3 +1,4 @@ + # yaml-language-server: $schema=https://schema.buildwithfern.dev/docs-yml.json instances: @@ -187,6 +188,8 @@ navigation: path: voice-fallback-plan.mdx - page: Transcriber fallback configuration path: customization/transcriber-fallback-plan.mdx + - page: Model fallback configuration + path: customization/model-fallback-plan.mdx - page: OpenAI realtime speech-to-speech path: openai-realtime.mdx - page: Provider keys diff --git a/fern/voice-fallback-plan.mdx b/fern/voice-fallback-plan.mdx index 7089d4b56..a41540f92 100644 --- a/fern/voice-fallback-plan.mdx +++ b/fern/voice-fallback-plan.mdx @@ -1,26 +1,27 @@ --- title: Voice fallback configuration -subtitle: Configure fallback voices that activate automatically if your primary voice fails +subtitle: Choose backup voices and troubleshoot failed fallback attempts slug: voice-fallback-plan -description: Configure fallback voices in Vapi that activate automatically when your primary voice provider fails, switching through your ordered list to keep calls live. +description: Configure an ordered voice fallback plan, test backup voices, and troubleshoot calls that end before fallback activates. --- ## Overview -Voice fallback configuration gives you the ability to continue your call in the event that your primary voice fails. Your assistant will sequentially fallback to only the voices you configure within your plan, in the exact order you specify. +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 `fallbackPlan.voices` to choose the backup voices and their order. - Without a fallback plan configured, your call will end with an error in the event that your chosen voice provider fails. + 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 failure occurs, Vapi will: -1. Detect the failure of the primary voice -2. If a custom fallback plan exists: - - Switch to the first fallback voice in your plan - - Continue through your specified list if subsequent failures occur - - Terminate only if all voices in your plan have failed +When a voice error triggers fallback, the assistant: + +1. Tries the first voice in `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 @@ -76,6 +77,27 @@ Add the `fallbackPlan` property to your assistant's voice configuration, and spe } ``` +## Troubleshoot voice fallback + +If a call ends instead of switching to a backup voice: + + + + Open [call logs](/observability/logs/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. + + + 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. + + + Make a test call with a known working backup voice as the primary voice. If it produces audio, you can use that provider as the primary voice for new calls while you investigate why the original provider did not switch. + + + If the test call still fails or fallback does not start, share the call ID, `endedReason`, and primary and backup providers with [Vapi support](/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. @@ -164,9 +186,9 @@ Each voice provider supports different configuration options. Expand the accordi ## Best practices -- Use **different providers** for your fallback voices to protect against provider-wide outages. +- 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 your fallback configuration to ensure smooth transitions between voices. +- Test the providers in your fallback configuration together to ensure smooth transitions between voices. ## FAQ