Skip to main content
You can control how a Retell agent pronounces specific words or phrases. Choose IPA, CMU, Mandarin Pinyin, or Cantonese Jyutping when the selected voice model supports it. To use the feature, you set a pronunciation dictionary on the agent. The dictionary is a list of entries, and each entry has:
  • Word or phrase to be annotated. For example, actually.
  • Phonetic alphabet supported by the selected voice.
  • Phoneme with the pronunciation in the selected alphabet.
For example: Use tone numbers 1–5 for Pinyin and 1–6 for Jyutping. Separate syllables with spaces.

​
Voice support

Which phonetic alphabets you can use depends on the selected voice provider and its effective voice model. The dashboard shows the supported alphabets under Pronunciation in the agent’s speech settings. See supported languages by provider for voice-model language restrictions. If an ElevenLabs voice uses Auto, an English-only agent resolves to Flash v2 and supports IPA and CMU. Agents that use other languages resolve to a newer ElevenLabs model that does not support pronunciation dictionaries. The dashboard displays the resulting support. The table lists the alphabets available in the dashboard. At runtime, Retell can convert CMU to IPA or IPA to CMU when the voice model supports the target alphabet. For example, Platform voices accept CMU entries that Retell converts to IPA. If neither native support nor a valid conversion is available, the entry stays in the dictionary but is not applied.

​
Edit and test a pronunciation

  1. In the agent’s Speech settings, open Pronunciation and add an entry, or open an existing entry to edit it.
  2. Enter the Word, select a supported Alphabet, and enter the Phoneme.
  3. Click Test Pronunciation to hear the entry with the selected agent’s voice. Adjust the phoneme and test again until it sounds right.
  4. Click Save for a new entry or Update for an existing one.
The test uses the values currently in the dialog, so you can preview a change before saving it. Testing is disabled when the word or phoneme is empty, or the selected alphabet is unsupported. If you change the agent’s voice or model, check the supported alphabets and test the pronunciation again.

​
How many entries can I add?

The pronunciation dictionary is a list on the agent — you can add multiple entries and there is no fixed cap enforced by the API. In practice:
  • Add one entry per word or short phrase you want to override. Each entry needs its own word, alphabet, and phoneme.
  • Keep the dictionary focused on words the model actually mispronounces (uncommon proper nouns, brand names, technical terms, foreign words). Overriding common words can produce unnatural speech.
  • Use a unique word value for each entry. The API rejects updates that contain duplicate word values.
  • Very large dictionaries can push the agent payload close to request size limits when calling update-agent. If you hit that, split entries across agents or trim rarely used words.

​
Manage the dictionary via the API

There is no dedicated pronunciation endpoint. The dictionary lives on the agent object, so manage it with the Update Agent endpoint through the pronunciation_dictionary field:
  • Send an array of entries, each with word, alphabet (ipa, cmu, pinyin, or jyutping), and phoneme.
  • The array you send replaces the existing dictionary, so include all entries you want to keep.
  • Set pronunciation_dictionary to null to remove the dictionary from the agent.

​
Finding the phonetic pronunciation

You can search online to find the phonetic pronunciation of a word, or use tools like: