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

# Control how your agent pronounces words

> Add a word list so your voice agent says brand names, acronyms, codes and place names the way you want, per language, from the dashboard or the API.

Text-to-speech voices are trained on general speech. They guess at your brand names, acronyms, product codes and place names, and they often guess wrong: an acronym read as one word, a number read the way you didn't want, a city in the wrong accent.

A pronunciation list fixes this. You add each word and how it should sound, and the agent says it that way everywhere it speaks: the welcome message, its replies, static messages and hand-in messages.

| Word | Sounds like |
| - | - |
| `HDFC` | H D F C bank |
| `KYC` | know your customer |
| `Pune` | Poona |
| `56` | five six |

***

## Supported voices

| Provider | Models |
| - | - |
| [ElevenLabs](https://www.bolna.ai/docs/elevenlabs-voice.md) | All models |
| [Cartesia](https://www.bolna.ai/docs/cartesia.md) | `sonic-3` and newer: `sonic-3`, `sonic-3.5`, `sonic-3.6` |

On other providers, the **Pronunciation** section doesn't appear, and a list saved over the API is ignored.

***

## Add words in the dashboard

**1. Pick the language**

Open the agent's **Languages** tab and select the language in the **Settings for** strip. The section title shows which language you are editing, for example **Pronunciation · Hindi**.

**2. Add a word**

In the **Pronunciation** section under **Voice**, type the word and how it should sound, then click **Add word** or press Enter.

**3. Save the agent**

The list is applied to calls a few seconds after you save.

![Pronunciation · Hindi section with a Search words box, Word and Pronounce as columns, an add row with an Add word button, rows KYC → नो योर कस्टमर and EMI → मासिक किस्त, and an Import button](https://mintcdn.com/bolna-54a2d4fe/4URLMQEyjDev1TMf/images/getting-started/agent-setup/pronunciation-table.png?fit=max\&auto=format\&n=4URLMQEyjDev1TMf\&q=85\&s=fa2984c0425d95a72a250b7fa57d58f4)

The Pronunciation section for Hindi, with two words in the list

Click a row to edit it. To delete several words at once, click **Select**, pick the rows and delete them.

### Import a list

Click **Import**, then **Import CSV** or **Import JSON**. You can also drop a file onto the table.

![Pronunciation · English section with the Import menu open, showing Import JSON and Import CSV](https://mintcdn.com/bolna-54a2d4fe/4URLMQEyjDev1TMf/images/getting-started/agent-setup/pronunciation-import-menu.png?fit=max\&auto=format\&n=4URLMQEyjDev1TMf\&q=85\&s=25cccfa54583eb0bab668261ff59cd14)

The Import menu under the word list

**CSV:** two columns, the word and how it sounds. A header row is optional. Save the file as UTF-8 so non-Latin scripts come through.

```csv theme={"system"}
word,pronunciation
HDFC,H D F C bank
KYC,know your customer
Pune,Poona
```

**JSON:** upload a file or paste it, in any of these shapes:

```json theme={"system"}
{ "HDFC": "H D F C bank", "KYC": "know your customer" }
```

```json theme={"system"}
[{ "word": "HDFC", "pronunciation": "H D F C bank" }]
```

```json theme={"system"}
[["HDFC", "H D F C bank"], ["KYC", "know your customer"]]
```

![Import JSON dialog for English with Upload file and Paste tabs, a paste box, and an open Format guide showing a JSON object of words and how they sound](https://mintcdn.com/bolna-54a2d4fe/4URLMQEyjDev1TMf/images/getting-started/agent-setup/pronunciation-import-json.png?fit=max\&auto=format\&n=4URLMQEyjDev1TMf\&q=85\&s=7de3a1d571f8b5b9b0f4cb0aa0c59bd5)

Import JSON with the Paste tab and the Format guide open

Before anything changes, a preview marks each row as **New**, **Overwrite**, **No change**, or skipped with the reason: no pronunciation, too long, or over the limit. Turn off **Overwrite existing words** to keep the words already in your list. If a file has the same word twice, the first one is used.

***

## Multilingual agents

Each language has its own list, so the same word can sound different in each language:

| Language | `56` sounds like |
| - | - |
| English | five six |
| Hindi | पाँच छह |
| Gujarati | પાંચ છ |

The agent uses the list of the language it is speaking and switches lists when it switches language. The welcome message uses the list of the language the call starts in.

***

## Limits and matching

* **Up to 100 words per agent**, across all its languages
* **A word** can be up to 50 characters, and **how it sounds** up to 100
* **Each word once per language.** `Bolna` and `bolna` count as the same word
* **Capitalization doesn't matter when matching.** A rule for `Pronutest` also covers `PRONUTEST` and `pronutest`
* **Phrases work.** `Blue Sky` → `orange moon` replaces the two words together

***

## Tips

* **Write how it sounds in the script the voice speaks.** For a Hindi voice, write `नो योर कस्टमर` rather than `know your customer`.
* **Spell out letters with spaces:** `H D F C`, not `HDFC`.
* **Match what the agent actually says.** A rule only applies to text the agent speaks. If your prompt lets the LLM write `fifty-six`, a rule for `56` won't apply, so ask the prompt to keep numbers and brand names exactly as written.
* **Test after the list is applied.** Save, wait until the status is `active` (see below), then place a test call.

***

## Over the API

Set `pronunciation_rules` on the synthesizer. Each entry is a `word` and how to `say_as` it.

**Single-language agent:**

```json theme={"system"}
"synthesizer": {
  "provider": "elevenlabs",
  "provider_config": {
    "voice": "Riya",
    "voice_id": "mfMM3ijQgz8QtMeKifko",
    "model": "eleven_turbo_v2_5"
  },
  "pronunciation_rules": [
    { "word": "HDFC", "say_as": "H D F C bank" },
    { "word": "Pune", "say_as": "Poona" }
  ]
}
```

**Multilingual agent:** set a list on each language in `multilingual_config.languages`:

```json theme={"system"}
"multilingual_config": {
  "enabled": true,
  "active_language": "en",
  "languages": {
    "en": {
      "synthesizer": {
        "provider": "elevenlabs",
        "provider_config": { "voice_id": "mfMM3ijQgz8QtMeKifko", "model": "eleven_turbo_v2_5" },
        "pronunciation_rules": [{ "word": "56", "say_as": "five six" }]
      }
    },
    "hi": {
      "synthesizer": {
        "provider": "elevenlabs",
        "provider_config": { "voice_id": "mfMM3ijQgz8QtMeKifko", "model": "eleven_turbo_v2_5" },
        "pronunciation_rules": [{ "word": "56", "say_as": "पाँच छह" }]
      }
    }
  }
}
```

* **Create and update** ([`POST`](https://www.bolna.ai/docs/api-reference/agent/v2/create) and [`PUT /v2/agent`](https://www.bolna.ai/docs/api-reference/agent/v2/update)): send the full lists.
* **[`PATCH /v2/agent/{agent_id}`](https://www.bolna.ai/docs/api-reference/agent/v2/patch_update)** with `agent_config.synthesizer.pronunciation_rules` replaces the list. On a multilingual agent, it replaces the list of the language the agent starts in. Send `[]` to clear it.
* **Invalid lists are rejected** with an error naming the problem (too many words, a duplicate word, or a value that's too long), and nothing changes.

### Check that the list is applied

[`GET /v2/agent/{agent_id}/pronunciation-dictionary-status`](https://www.bolna.ai/docs/api-reference/agent/v2/get_pronunciation_status) returns:

| `status` | Meaning |
| - | - |
| `active` | Every list is applied to calls. |
| `pending` | Being applied. This usually takes a few seconds after a save. |
| `failed` | Couldn't be applied. Save the agent again. |
| `null` | The agent has no word list on a supported voice. |

***

## Using your own provider key

If you connected your own ElevenLabs or Cartesia key under **Providers**, the list is created in your provider account, where you'll see it named `bolna-…`, and calls use your key. If you remove your key later, save the agent again so the list is applied without it.

You can also attach pronunciation dictionaries you made in your provider's dashboard. This works over the API, with your own key connected:

* **ElevenLabs:** `provider_config.pronunciation_dictionary_locators`, up to 3, each with a `pronunciation_dictionary_id` and `version_id`
* **Cartesia:** `provider_config.pronunciation_dict_id`, on `sonic-3` and newer

Bolna checks that each dictionary exists in your account when you save, and rejects the save if one doesn't. Use either your own dictionaries or a word list on a voice, not both. If a dictionary is deleted later, calls keep going without it, and the call log shows the error.

***

## FAQ

> **Why don't I see the Pronunciation section?**
>
> The voice's provider or model doesn't support it. Switch to ElevenLabs, or to Cartesia `sonic-3` or newer.

> **I saved a word but the agent still says it the old way**
>
> Check that the status is `active`, and that you added the word under the language the agent was speaking. Then check the call transcript: the rule only applies if the agent's reply contains the word exactly as you wrote it.

> **Can one word sound different in two languages?**
>
> Yes. Each language has its own list, so `56` can be "five six" in English and "पाँच छह" in Hindi.

***

## Related

* [Languages Tab](https://www.bolna.ai/docs/agent-setup/audio-tab.md): where the Pronunciation section lives in the dashboard
* [Writing prompts in non-English languages](https://www.bolna.ai/docs/writing-prompts-in-non-english-languages.md): getting natural speech in every language
* [Patch update agent](https://www.bolna.ai/docs/api-reference/agent/v2/patch_update.md): update the list over the API


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