docs: voice fallback plan (#44)

Author: bryantanderson

fern/docs.yml

@@ -243,6 +243,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,78 @@
+---
+title: Voice Fallback Plan
+subtitle: Configure fallback voices that activate automatically if 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
+
+By default, if an assistant's primary voice experiences any failure, Vapi will automatically attempt to use other available voices to continue the call. While this ensures call continuity, you might want more control over which specific voices are used as fallbacks.
+
+Fallback plans give you precise control over the fallback sequence. Your assistant will sequentially fallback to only the voices you configure within your plan, in the exact order you specify. 
+
+## 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
+3. If no custom fallback plan is configured:
+  - Automatically switch to other available voices
+  - Continue attempting different voices
+  - Terminate only if all available voices have failed
+
+## Configuration
+
+Add the `fallbackPlan` property to your assistant's voice configuration, and specify the fallback voices within the `voices` property.
+- Please note that fallback voices must be valid JSON configurations, and not strings.
+- The order matters. Vapi will choose fallback voices starting from the beginning of the list.
+
+```json
+{
+  "voice": {
+    "provider": "openai",
+    "voiceId": "shimmer",
+    "fallbackPlan": {
+        "voices": [
+            {
+                "provider": "cartesia",
+                "voiceId": "248be419-c632-4f23-adf1-5324ed7dbf1d"
+            },
+            {
+                "provider": "playht",
+                "voiceId": "jennifer"
+            }
+        ]
+    }
+  }
+}
+```
+
+Although **not recommended**, you may choose to disable the default fallback behavior by providing an empty list of voices in your fallback plan:
+
+```json
+{
+  "voice": {
+    "provider": "openai",
+    "voiceId": "shimmer",
+    "fallbackPlan": {
+        "voices": []
+    }
+  }
+}
+```
+
+## 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.