Pronunciation Dictionary

The pronunciation dictionary tells the agent’s voice how to say specific words. Each entry pairs a word with a pronunciation: whenever the agent is about to say the word, the voice reads the pronunciation instead.

Use it for terms the voice gets wrong on its own, such as brand names (“Phood” read as “fud”), place names (“Phuket”), acronyms you want read a particular way, or product names with unusual spellings.

Writing entries

Write the pronunciation as a respelling in ordinary letters, the way you’d want it read aloud:

The pronunciation is passed to the voice as plain text. There is no phoneme, IPA, or SSML syntax.

How matching works

When the agent speaks, each entry’s word is replaced by its pronunciation before the text reaches the voice:

• Case-insensitive. Phood also matches phood and PHOOD.
• Whole words only. Phood matches “Phood” and “Phood’s”, but not “Phoods” or “Phoodie”. Add a separate entry for each form you need, such as Phoods → foods.
• Applies to everything the agent says, including the welcome message.
• Transcripts keep the original word. With Phonic voices, the conversation transcript shows “Phood”, not “food”.

Configure it in the dashboard

1. Open your agent and go to the Advanced tab.
2. Under Pronunciation dictionary, click Add word.
3. Enter the word in the first field and its pronunciation in the second.
4. Save the agent.

Use the trash icon next to an entry to remove it.

Configure it with the API

Set pronunciation_dictionary to a list of { word, pronunciation } objects when you create or update an agent:

await client.agents.update("phantastic-phood-host", {
  project: "main",
  pronunciation_dictionary: [
    { word: "Phood", pronunciation: "food" },
    { word: "Phoods", pronunciation: "foods" },
  ],
});

Updating pronunciation_dictionary replaces the whole list. To add one entry, send the existing entries plus the new one. To clear the dictionary, send [].

You can also set pronunciation_dictionary for a single conversation, in the WebSocket config message or in the response from your agent configuration endpoint. A list provided there replaces the agent’s dictionary for that conversation; it isn’t merged with it.

Limits

Both fields are required and are trimmed of leading and trailing spaces. Each word can appear only once, compared case-insensitively, so Phood and phood can’t both be entries.

Common mistakes

The pronunciation is dropped into the agent’s speech exactly as written, so anything in it gets said out loud.