docs: add legacy voice migration guide for Vapi Voices (#900)

Author: vapi-tasker[bot]

fern/docs.yml

@@ -558,8 +558,12 @@ navigation:
               - section: Voices (Text-to-speech)
                 icon: fa-light fa-waveform-lines
                 contents:
-                  - page: Vapi Voices
+                  - section: Vapi Voices
                     path: providers/voice/vapi-voices.mdx
+                    contents:
+                      - page: Legacy migration
+                        path: providers/voice/vapi-voices/legacy-migration.mdx
+                        icon: fa-light fa-triangle-exclamation
                   - page: ElevenLabs
                     path: providers/voice/elevenlabs.mdx
                   - page: PlayHT

fern/providers/voice/vapi-voices.mdx

@@ -5,12 +5,7 @@ slug: providers/voice/vapi-voices
 ---
 
 <Warning>
-**Legacy Voice Notice:** The following voices are being phased out: **Paige, Spencer, Neha, Harry, Cole, Hana, Lily, Kylie**
-- Existing assistants using these voices may continue to use them during the transition period
-- New assistants cannot be created using legacy voices
-- Legacy voices will be fully retired in a future update
-
-We recommend using one of the Active Voices listed below.
+**Voice Update:** Some legacy voices (Spencer, Neha, Harry, Cole, Paige, Hana, Lily, Kylie, Rohan) are being retired on March 1, 2026. If you're using any of these voices, please review the migration guide. [Learn more →](/providers/voice/vapi-voices/legacy-migration)
 </Warning>
 
 ## What are Vapi Voices?
@@ -28,13 +23,6 @@ Vapi Voices is our carefully curated selection of high-quality voices designed t
 
 These voices are fully supported and recommended for new assistants.
 
-### Rohan
-- **Gender**: Male
-- **Accent**: Indian American
-- **Age**: 24 years old
-- **Characteristics**: Bright, optimistic, cheerful, energetic
-- **Sample Audio**: <audio controls src="/static/audio/rohan-sample.wav">Your browser does not support the audio element.</audio>
-
 ### Elliot
 - **Gender**: Male
 - **Accent**: Canadian

fern/providers/voice/vapi-voices/legacy-migration.mdx

@@ -0,0 +1,80 @@
+---
+title: Legacy voice migration guide
+subtitle: Learn to migrate from legacy Vapi Voices before March 1, 2026
+slug: providers/voice/vapi-voices/legacy-migration
+---
+
+## Voice availability update
+
+We're updating Vapi Voices. The following legacy voices are being phased out and will be retired on **March 1, 2026**:
+
+- Spencer
+- Neha
+- Harry
+- Cole
+- Paige
+- Hana
+- Lily
+- Kylie
+- Rohan
+
+## What this means
+
+- **Existing assistants** using these voices will continue to work during the transition period
+- **New assistants** can no longer be created using legacy voices
+- **After March 1, 2026**, any assistants still using legacy voices will be automatically switched to the default replacement voice (Option 1 in the table below)
+
+## Replacement voice mapping
+
+We've selected replacement voices from ElevenLabs using their voice matching tool to find the closest match in tone and style. These voices are priced similarly to your existing voice.
+
+<Note>
+**Option 1 is the default fallback** — if you don't switch by March 1, your assistant will automatically be switched to the Option 1 voice.
+</Note>
+
+| Legacy Voice | Option 1 (Default Fallback) | Option 2 | Option 3 |
+|--------------|----------------------------|----------|----------|
+| Spencer | Penelope - `JpjuQfOymR78GvGgYe0U` | Marissa - `L0yTtpRXzdyzQlzALhgD` | Larissa - `StXdHzik5guDrDk6fg3m` |
+| Neha | Navya Kannan - `Lw21wLjWqPPaL3TcYWek` | Riya Rao - `l69wlWTZVIKv0UxMucTn` | Simran - `1ea3IFhmSWgw8sJkSvfJ` |
+| Harry | Rick - `hUcrqyP5BNIsY3bMyY9A` | Piksel - `iq1GS1mcjc63xtqTrsFh` | Micheal - `F6d1zUrtT0hMMRrPcNx3` |
+| Cole | Terrence - `MFeqle9Un0xiXpndMbD7` | James - `IdAziNk2dxibsP2mRgAK` | Derek - `Q0Et7LOU7VpeoeCRQAVS` |
+| Paige | Jöne - `UShdpPZj9t1Kgb9ACOS2` | Nessa - `6qA4mbnKOyDYLLQmx3n5` | Kimber - `fQ74DTbwd8TiAJFxu9v8` |
+| Hana | Celeste - `wSRCyzJYBsTZLFcumuu8` | Freya - `u8ADrbquiJqufR9XMtb8` | Seema - `sLoLgWyZ6rs3nXR71t49` |
+| Lily | Tanya - `7sAIIIXrQKek5xiLc1R6` | Melissa - `JH3fX8OSjg6sNdEtPjxr` | Ariel - `TPbSfDVirzpiSkim8gMw` |
+| Kylie | Chanelle - `t5ztDJA7pj9EyW9QIcJ2` | Aryannah - `vOJuCTA36jkG6q1OskrK` | Riley - `kXsOSDWolD7e9l1Z0sbH` |
+| Rohan | Manav - `T8lgQl6x5PSdhmmWx42m` | Elixified - `xCyfAutjCrYQhbBDS4l8` | Joseph - `8fcyCHOzlKDlxh1InJSf` |
+
+## FAQs
+
+<AccordionGroup>
+  <Accordion title="How were the replacement voices selected?">
+    We used ElevenLabs' voice matching tool to find the most appropriate replacements for each legacy voice based on tone, style, and characteristics. Replacements are from the same provider at the same pricing.
+  </Accordion>
+
+  <Accordion title="What happens if I don't switch by March 1?">
+    Any assistants still using legacy voices after March 1, 2026 will be automatically switched to the Option 1 (default fallback) voice shown in the table above.
+  </Accordion>
+
+  <Accordion title="Will my pricing change?">
+    Replacement voices were chosen at the same pricing.
+  </Accordion>
+
+  <Accordion title="How do I switch my voice now?">
+    You can switch your assistant's voice in two ways:
+
+    1. **Dashboard:** Go to your assistant settings and select a new voice from the dropdown
+    2. **API:** Update the `voiceId` field in your assistant configuration via the API
+  </Accordion>
+
+  <Accordion title="Can I choose a different replacement voice?">
+    Yes! We provide three recommended options for each legacy voice, but you're free to choose any available voice that fits your needs. We encourage you to switch before March 1 so you can select the voice that works best for you.
+  </Accordion>
+
+  <Accordion title="I'm an Enterprise customer — can I get help with the transition?">
+    Yes. Your account team will reach out with personalized support. If you have questions in the meantime, contact your account team directly.
+  </Accordion>
+
+  <Accordion title="Who can I contact if I have questions?">
+    Reach out to [[email protected]](mailto:[email protected]) or contact your account team if you're an Enterprise customer.
+  </Accordion>
+</AccordionGroup>