> ## Documentation Index
> Fetch the complete documentation index at: https://docs.callers.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pronunciation dictionary

> Teach your agent how to say brand names, people's names, and technical terms by defining custom pronunciations.

Voices sometimes mispronounce brand names, surnames, place names, acronyms, or industry terms. A pronunciation dictionary fixes this: you list the words, define how each should sound, and the agent uses that pronunciation every time the word appears in what it says.

The dictionary changes only how the agent **speaks**. To help the agent **understand** a word when the contact says it, use [Speech recognition vocabulary](https://docs.callers.ai/documentation/voice/speech-recognition-vocabulary.md).

## How it works

Each entry has:

| Field | What it is |
| - | - |
| **Word** | The word or phrase as it appears in your script or in the agent's replies. Matching is case-insensitive and whole-word only, so `Callers` also matches `callers` but not `Callersville`. |
| **IPA** | The pronunciation in the International Phonetic Alphabet, for example `ˈkɔːlərz`. |
| Phonetic spelling | A readable respelling, generated for you from the IPA. Hover an entry to see it. |

When the agent speaks, every match of the word is replaced with its defined pronunciation before the voice reads it.

## Add a pronunciation to an agent

**1. Open the agent's voice settings**

Open the agent and click **Agent** in the editor header (see [Agent settings](https://docs.callers.ai/documentation/build-your-agent/agent-setup.md#agent-voice-and-conversation)), then expand **Pronunciation Dictionaries**.

**2. Enter the word**

Type the word in **Word**. When you leave the field, Callers generates suggested pronunciations.

**3. Choose or write the IPA**

Click the **IPA** field to see the suggestions. Play each one with the speaker icon to hear it in the agent's voice, then select the right one. You can also type your own IPA.

**4. Add it**

Click **Add**. The entry appears as a chip below the fields. Click its speaker icon to hear it, or remove it with the delete icon.

**5. Save and test**

Save the agent and make a [test call](https://docs.callers.ai/documentation/build-your-agent/testing-your-agent.md) that uses the word.

> [!TIP]
>
> If none of the suggestions sound right, start from the closest one and edit the IPA by hand. Small changes, such as moving the stress mark `ˈ`, often fix the problem. For how to write numbers, emails, and names so the agent says them correctly, see [Prompting voice agents](https://docs.callers.ai/documentation/best-practices/prompting-voice-agents.md#numbers-dates-emails-and-links).

## Shared dictionaries

> [!NOTE]
>
> This feature is enabled per account. Contact [support@callers.ai](mailto:support@callers.ai) to turn it on.

If several agents use the same names and terms, keep them in a shared dictionary for your organization instead of repeating entries in each agent. Contact support to set up shared dictionaries for your account.

To use a shared dictionary in an agent:

1. Open the agent, click **Agent**, and expand **Pronunciation Dictionaries**.
2. Click **Connect Pronunciation Dictionaries** and select the dictionaries this agent should use.
3. Save the agent. The button changes to **Pronunciation Dictionaries Connected**.

You can combine connected dictionaries with entries added directly to the agent.

## Best practices

* **Add only words that are wrong.** Most words are pronounced correctly; extra entries add maintenance without benefit.
* **Include common variants.** Add plural or possessive forms separately if they appear in your script, for example `Acme` and `Acme's`.
* **Spell out acronyms you want read letter by letter**, such as `CRM` or `HVAC`, if the voice reads them as a word.
* **Re-check after changing the voice or language.** Different voices interpret IPA slightly differently. Play your entries again with the new voice.
* **Keep variable values in mind.** Names that come from contact data (for example `{{name}}`) are matched too, so add frequent surnames or city names your contacts have.

## Troubleshooting

> **The agent still mispronounces the word**
>
> Check that the **Word** matches how it is written in the script or how the agent writes it in replies, including spaces and hyphens. Whole-word matching means `Acme` doesn't match `AcmeCorp`.

> **The Add button is disabled**
>
> Both **Word** and **IPA** are required. Select a suggestion or type IPA first.

> **I don't see Connect Pronunciation Dictionaries**
>
> The button appears only when shared dictionaries are enabled for your account and at least one dictionary exists. Contact support.

## Related

> **[Speech recognition vocabulary](https://docs.callers.ai/documentation/voice/speech-recognition-vocabulary.md)**
>
> Help the agent understand names and terms.

> **[Voices and sounds](https://docs.callers.ai/documentation/voice/voices-and-sounds.md)**
>
> Choose and tune the agent's voice.

> **[Supported languages](https://docs.callers.ai/documentation/using-callers/supported-languages.md)**
>
> Languages and dialects.

> **[Variables](https://docs.callers.ai/documentation/build-your-agent/agent-variables.md)**
>
> Personalize scripts with contact data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.