Skip to main content
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.

​
Supported voices

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

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

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.
JSON: upload a file or paste it, in any of these shapes:
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

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: 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:
Multilingual agent: set a list on each language in multilingual_config.languages:
  • Create and update (POST and PUT /v2/agent): send the full lists.
  • PATCH /v2/agent/{agent_id} 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 returns:

​
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

The voice’s provider or model doesn’t support it. Switch to ElevenLabs, or to Cartesia sonic-3 or newer.
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.
Yes. Each language has its own list, so 56 can be “five six” in English and “पाँच छह” in Hindi.