add docs for fallback plan

Author: bryantanderson

fern/docs.yml

@@ -244,6 +244,8 @@ navigation:
             path: tools-calling.mdx
           - page: Prompting Guide
             path: prompting-guide.mdx
+          - page: Voice Fallback Plan
+            path: voice-fallback-plan.mdx
           - page: OpenAI Realtime 
             path: openai-realtime.mdx
       - section: Glossary

fern/voice-fallback-plan.mdx

@@ -0,0 +1,58 @@
+---
+title: Voice Fallback Plan
+subtitle: You can configure your assistants to fallback to other voices when your primary voice fails.
+slug: voice-fallback-plan
+---
+
+<Note>
+  Voice fallback plans can currently only be configured through the API. We are working on making this available through our dashboard.
+</Note>
+
+## Introduction
+
+Prior to the addition of fallback plans, calls would terminate if an assistant's voice experienced any failure, regardless of whether the issue originated from the voice provider or Vapi.
+
+Fallback plans allow your assistant to continue the call in the scenario that your primary voice fails. Your assistant will sequentially fallback to the voices you configure within your plan, until there are no voices left. 
+
+## How It Works
+
+When a voice failure occurs, Vapi will:
+1. Detect the failure of the primary voice
+2. Automatically switch to the first fallback voice
+3. Continue through the list of fallback voices if subsequent failures occur
+4. Only terminate if all configured fallback voices fail
+
+## Configuration
+
+Add the `fallbackPlan` property to your assistant's voice configuration. Specify a list of voices within the `voices` property of `fallbackPlan`, and you're done!
+- Please note that fallback voices must be valid JSON configurations, and not strings.
+
+```json
+{
+  "voice": {
+    "provider": "openai",
+    "voiceId": "shimmer",
+    "fallbackPlan": {
+        "voices": [
+            {
+                "provider": "cartesia",
+                "voiceId": "248be419-c632-4f23-adf1-5324ed7dbf1d",
+            },
+            {
+                "provider": "playht",
+                "voiceId": "jennifer"
+            }
+        ]
+    }
+  }
+}
+```
+
+## Best practices
+
+- Use <b>different providers</b> for your fallback voices to protect against provider-wide outages.
+- Select voices with similar characteristics (tone, accent, gender) to maintain consistency in the user experience.
+
+## How will pricing work?
+
+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.