> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phonely.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Voice
> Choose, configure, and test how your agent sounds during calls.
Voice controls the speech callers hear during phone conversations. The selected voice and its settings belong to the agent and apply across its inbound and outbound flows.
Use [Guidelines](/agent-design/guidelines) to control the agent's personality, tone, and response style. Voice controls how those responses sound when spoken.
## Choose a voice
Open **Agent Design**, then select **Voice**.
1. Play a voice to preview it with the sample text in the test card.
2. Search by voice name or filter the library by language, gender, accent, or other available traits.
3. Select the voice you want the agent to use.
The selected voice appears first in the library. Use the heart control to save favorites, and use **Mine** to view voices owned by you or your organization. To give one of these voices a clearer label, select **Rename voice** in its row, enter a name, and select **Save**. Renaming is unavailable while the agent is read-only.
Choose a voice that remains clear at phone-call audio quality and fits the conversations the agent handles. Accent, pacing, and pronunciation are usually more important than how expressive a voice sounds in a short sample.
## Customize the voice
Use **Voice Settings** to adjust the selected voice. Changes save automatically.
| Setting | What it controls |
| :- | :- |
| **Speed** | How quickly the agent speaks; range varies by provider |
| **Languages** | Which languages the agent understands and replies in |
| **Background Noise** | Optional office ambience and its volume |
| **Pronunciations** | How Cartesia voices pronounce specific names or terms |
### Choose the agent's languages
**Languages** is the single control for what your agent hears and says. New agents start with English.
What you can choose depends on two things:
* **The transcriber.** Each speech recognition engine supports its own set of languages. Switching engines keeps only the languages the new one accepts.
* **The selected voice.** A voice that speaks one language limits the agent to that language. Choose a Spanish-only voice on an English agent and the agent handles Spanish, not both.
When only one language is available, the control becomes a single choice and explains why. If a multi-language selection has to narrow, an inline message and a toast name the voice and the one language the agent will use.
Select only the languages your callers actually use. Extra languages give the agent more ways to mishear a caller without improving the conversations you expect.
### Add pronunciations
**Pronunciations** is available for Cartesia voices. Add an entry when the agent needs to say a name, brand, acronym, or specialized term consistently.
Enter the written word and its pronunciation, then play the entry before saving it. Expand **Phonemes** only when the generated pronunciation needs a precise adjustment.
### Configure transcription
Expand **Advanced** in Voice Settings to add **Transcription Keywords**, which help the transcriber recognize uncommon names, product terms, or identifiers.
The **Transcriber** itself is selected in **Agent Settings > Advanced > Interruptions Control**. Keep the default unless testing shows that another engine better fits the language or audio conditions of your calls. Changing the engine keeps your language selections compatible with it and applies that engine's interruption defaults.
## Test the voice
Enter a representative sentence in the test card. Include names, numbers, or specialized terms the agent will commonly say.
1. Preview several voices with the same text so the comparison is meaningful.
2. Select a voice, adjust its settings, and preview it again.
3. Confirm the pronunciation, pace, and background sound before testing the complete agent.
4. Use **Web Call** to hear the voice in a real conversation and check turn-taking, interruptions, and phone-call audio quality.
A voice preview tests synthesized speech, not the complete call experience. Always complete a Web Call before relying on a new voice or major setting change.
## Add or clone a voice
Select **Add or Clone a Voice** when the built-in library does not contain the voice you need.
Choose **Add a voice**, then select the provider and model. Enter the voice ID from the provider and select its language. Add an optional **Name** to label the voice in your library, or leave it blank to use a name derived from the provider's voice name. Adding the voice also selects it for the current agent, so test it before using the agent for live calls.
To compare the same provider voice on different models, add it again with the same voice ID and a different model. Each model has its own library entry. Give the entries distinct names so you can tell them apart when choosing a voice. The form prevents adding the same provider voice ID on the same model again.
Choose **Clone a voice**, then upload or record a clear 1–2 minute sample. Enter a unique name, gender, and language, and confirm that you have permission to clone and use the recording. Compare the generated samples before saving one. The saved voice becomes the current agent's selected voice.
## Troubleshooting
Either the selected voice speaks a single language, or the transcriber does not support that language. Select a multi-lingual voice, or change the transcriber in **Agent Settings > Advanced > Interruptions Control**, then set **Languages** again.
If the selected voice supports **Pronunciations**, add the word and test a clearer pronunciation. If the setting is unavailable, select a Cartesia voice or another voice that already pronounces the term correctly.
Confirm that the intended voice is still selected and rerun the preview after changing Speed, Background Noise, or Pronunciations. Then use Web Call: phone audio, caller interruptions, and the surrounding conversation are not represented by an isolated voice preview.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.