From b6025e3961b6c10bb6216238730b69a96f0dd380 Mon Sep 17 00:00:00 2001 From: Bryant Date: Wed, 20 Nov 2024 15:43:52 +1100 Subject: [PATCH 1/3] add docs for fallback plan --- fern/docs.yml | 2 ++ fern/voice-fallback-plan.mdx | 58 ++++++++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+) create mode 100644 fern/voice-fallback-plan.mdx diff --git a/fern/docs.yml b/fern/docs.yml index 189f4fd0..897a643c 100644 --- a/fern/docs.yml +++ b/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 diff --git a/fern/voice-fallback-plan.mdx b/fern/voice-fallback-plan.mdx new file mode 100644 index 00000000..16bf106e --- /dev/null +++ b/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 +--- + + + Voice fallback plans can currently only be configured through the API. We are working on making this available through our dashboard. + + +## 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 different providers 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. \ No newline at end of file From e860577021ba76b702c285adb0223bd145a46fc2 Mon Sep 17 00:00:00 2001 From: Bryant Date: Fri, 22 Nov 2024 09:34:32 +1100 Subject: [PATCH 2/3] more tweaks --- fern/voice-fallback-plan.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/fern/voice-fallback-plan.mdx b/fern/voice-fallback-plan.mdx index 16bf106e..67c8977f 100644 --- a/fern/voice-fallback-plan.mdx +++ b/fern/voice-fallback-plan.mdx @@ -20,12 +20,13 @@ 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 +4. Only terminate if the list of fallback voices has been exhausted, and all have failed ## 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! +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. +- Also note that the order matters. Vapi will choose fallback voices starting from the beginning of the list. ```json { From 2f7d553031458fce2cd32211492c5d2494d40d24 Mon Sep 17 00:00:00 2001 From: Bryant Date: Wed, 27 Nov 2024 21:59:50 +1100 Subject: [PATCH 3/3] refactor docs --- fern/voice-fallback-plan.mdx | 37 +++++++++++++++++++++++++++--------- 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/fern/voice-fallback-plan.mdx b/fern/voice-fallback-plan.mdx index 67c8977f..8461983d 100644 --- a/fern/voice-fallback-plan.mdx +++ b/fern/voice-fallback-plan.mdx @@ -1,6 +1,6 @@ --- title: Voice Fallback Plan -subtitle: You can configure your assistants to fallback to other voices when your primary voice fails. +subtitle: Configure fallback voices that activate automatically if your primary voice fails. slug: voice-fallback-plan --- @@ -10,23 +10,28 @@ slug: voice-fallback-plan ## 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. +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 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. +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. Automatically switch to the first fallback voice -3. Continue through the list of fallback voices if subsequent failures occur -4. Only terminate if the list of fallback voices has been exhausted, and all have failed +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. -- Also note that the order matters. Vapi will choose fallback voices starting from the beginning of the list. +- The order matters. Vapi will choose fallback voices starting from the beginning of the list. ```json { @@ -37,7 +42,7 @@ Add the `fallbackPlan` property to your assistant's voice configuration, and spe "voices": [ { "provider": "cartesia", - "voiceId": "248be419-c632-4f23-adf1-5324ed7dbf1d", + "voiceId": "248be419-c632-4f23-adf1-5324ed7dbf1d" }, { "provider": "playht", @@ -49,10 +54,24 @@ Add the `fallbackPlan` property to your assistant's voice configuration, and spe } ``` +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 different providers 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. +- Select voices with **similar characteristics** (tone, accent, gender) to maintain consistency in the user experience. ## How will pricing work?