Pronunciation Management

Overview

Pronunciation Management allows you to define custom pronunciations for words that your agent frequently mispronounces — brand names, product names, technical terms, acronyms, and industry-specific vocabulary. Best for:

Companies with unique brand/product names
Technical support with specialized terminology
Medical/legal professionals with industry jargon
Non-English words in English conversations
Acronyms and abbreviations

Why Pronunciation Matters

Common Mispronunciation Problems:

Word Type	Example	Common Error
Brand Names	”Nike"	"Nike” (like spike) vs “Ni-key”
Acronyms	”API"	"API” (as word) vs “A-P-I”
Technical Terms	”MySQL"	"My-sequel” vs “My-S-Q-L”
Non-English	”Hermès"	"Her-mez” vs “Her-mess”
Product Names	”iPhone"	"i-Phone” vs “iPhone”

Impact: Correct pronunciation builds credibility and trust. Mispronunciation can confuse customers and damage brand perception.

How It Works

Agent needs to say "MySQL database"
         │
         ▼
Check pronunciation dictionary
         │
         ▼
Found: "MySQL" → "my-ess-que-ell"
         │
         ▼
TTS uses custom phonemes
         │
         ▼
User hears correct pronunciation

Step 1: Identify Problem Words

Common Categories

Brand & Product Names:

Your company name
Product names
Competitor names (if mentioned)
Partner brands

Technical Terminology:

Programming languages (Python, JavaScript)
Protocols (HTTP, TCP/IP)
Software names (Kubernetes, Docker)
Industry-specific terms

People & Places:

Employee names
Office locations
Customer names (if in CRM)

Acronyms & Abbreviations:

Company acronyms (CEO, CFO)
Technical acronyms (API, SDK, IDE)
Industry abbreviations

Testing for Mispronunciations

Test your agent with a script containing key terms
Note any mispronunciations
Prioritize frequently used words
Create pronunciation entries for each

Step 2: Create Pronunciation Entry

Via Studio

Go to Agent Settings → Pronunciations
Click Add Pronunciation
Fill in the details:

Field	Description	Example
Word	The word as it appears in text	`MySQL`
Phoneme	How it should be pronounced (IPA or simplified)	`my-ess-que-ell`

Click Save

Via API

POST /api/pronunciations/{agentId}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "word": "MySQL",
  "phoneme": "my-ess-que-ell"
}

Response:

{
  "success": true,
  "pronunciation": {
    "id": "pronun_abc123",
    "word": "MySQL",
    "phoneme": "my-ess-que-ell",
    "agentId": "agent_xyz789",
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:00:00Z"
  }
}

Step 3: Writing Phonemes

Phoneme Formats

Format 1: Simplified Phonetic (Recommended) Easy-to-read phonetic spelling:

Word	Phoneme	Explanation
`Nike`	`ny-key`	Two syllables
`MySQL`	`my-ess-que-ell`	Spell out each letter
`Hermès`	`air-mez`	Approximate French
`Kubernetes`	`koo-ber-net-eez`	Break into syllables

Format 2: IPA (International Phonetic Alphabet) For advanced users:

Word	IPA Phoneme
`Nike`	`ˈnaɪki`
`MySQL`	`maɪ ɛs kju ɛl`
`Hermès`	`ɛʁˈmɛz`

Recommendation: Use simplified phonetic spelling unless you’re familiar with IPA. It’s easier to read and debug.

Phoneme Guidelines

Use Hyphens for Syllables

Break words into syllables: koo-ber-net-eez not kooberneteez

Spell Out Acronyms

API → ay-pee-eye, not api

Indicate Stress

Capitalize stressed syllables: kuh-LOO-dih for “cloud”

Use Common Conventions

“ph” → “f” sound, “sh” → “sh” sound, “th” → “th” sound

Test Iteratively

Create entry → Test → Adjust → Repeat until correct

Keep It Simple

Use familiar letter combinations. Avoid obscure symbols.

Examples by Category

Technology:

[
  { "word": "API", "phoneme": "ay-pee-eye" },
  { "word": "SQL", "phoneme": "ess-que-ell" },
  { "word": "Linux", "phoneme": "LIN-ooks" },
  { "word": "GIF", "phoneme": "jif" },
  { "word": "Docker", "phoneme": "DAH-ker" },
  { "word": "Kubernetes", "phoneme": "koo-ber-net-eez" }
]

Brand Names:

[
  { "word": "Nike", "phoneme": "NY-key" },
  { "word": "Adidas", "phoneme": "AH-dee-dahs" },
  { "word": "Hermès", "phoneme": "air-MEZ" },
  { "word": "Louis Vuitton", "phoneme": "LOO-ee vwee-TAHN" },
  { "word": "Porsche", "phoneme": "POR-shuh" }
]

Company-Specific:

[
  { "word": "AcmeCorp", "phoneme": "AK-mee-korp" },
  { "word": "DataSync", "phoneme": "DAY-tuh-sink" },
  { "word": "CloudFlex", "phoneme": "KLOWD-flex" },
  { "word": "TechOps", "phoneme": "tek-OPS" }
]

People Names:

[
  { "word": "Siobhan", "phoneme": "shih-VAWN" },
  { "word": "Nguyen", "phoneme": "win" },
  { "word": "Micheál", "phoneme": "mee-KAWL" },
  { "word": "Saoirse", "phoneme": "SEER-shuh" }
]

Step 4: Manage Pronunciations

List Pronunciations

Via Studio:

Go to Agent Settings → Pronunciations
See all custom pronunciations

Via API:

GET /api/pronunciations/{agentId}
Authorization: Bearer YOUR_API_KEY

Response:

{
  "success": true,
  "pronunciations": [
    {
      "id": "pronun_abc123",
      "word": "MySQL",
      "phoneme": "my-ess-que-ell",
      "agentId": "agent_xyz789",
      "createdAt": "2024-01-10T09:00:00Z",
      "updatedAt": "2024-01-10T09:00:00Z"
    },
    {
      "id": "pronun_def456",
      "word": "API",
      "phoneme": "ay-pee-eye",
      "agentId": "agent_xyz789",
      "createdAt": "2024-01-11T14:30:00Z",
      "updatedAt": "2024-01-11T14:30:00Z"
    }
  ]
}

Update Pronunciation

Via Studio:

Go to Agent Settings → Pronunciations
Click Edit (pencil icon)
Modify word or phoneme
Save changes

Via API:

PUT /api/pronunciations/{agentId}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "pronunciationId": "pronun_abc123",
  "word": "MySQL",
  "phoneme": "my-ess-que-ell"
}

Delete Pronunciation

Via Studio:

Go to Agent Settings → Pronunciations
Click Delete (trash icon)
Confirm deletion

Via API:

DELETE /api/pronunciations/{agentId}?pronunciationId={pronunciationId}
Authorization: Bearer YOUR_API_KEY

Advanced Features

Bulk Import

Import multiple pronunciations at once: Via API:

POST /api/pronunciations/{agentId}/bulk
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "pronunciations": [
    { "word": "API", "phoneme": "ay-pee-eye" },
    { "word": "SQL", "phoneme": "ess-que-ell" },
    { "word": "Linux", "phoneme": "LIN-ooks" },
    { "word": "GIF", "phoneme": "jif" }
  ]
}

Pronunciation Templates

Use pre-built templates for common categories: Available Templates:

Tech Startup: Common tech terms and acronyms
E-Commerce: Product and brand name conventions
Healthcare: Medical terminology
Legal: Legal terms and Latin phrases
Finance: Financial terms and company types

Apply Template:

Go to Agent Settings → Pronunciations
Click Import Template
Select category
Review and customize
Click Apply

Case Sensitivity

Pronunciations are case-insensitive by default:

Entry for “MySQL” applies to: MySQL, mysql, MYSQL
Entry for “API” applies to: API, Api, api

If you need different pronunciations for different cases (rare), create separate entries.

Best Practices

Start Small

Begin with 5-10 critical words. Add more as you identify issues during testing.

Test with Real Audio

Listen to actual agent output. Don’t assume the phoneme is correct without testing.

Document Your Choices

Keep a record of why certain words are pronounced a certain way (especially brand names).

Update Regularly

Add new product names, remove discontinued products, update as needed.

Consider Your Audience

Use pronunciations familiar to your target audience, not necessarily dictionary-correct.

Be Consistent

Use the same phoneme conventions across all entries (e.g., always hyphenate syllables).

Troubleshooting

Pronunciation isn't changing

Check:

Is the word spelled exactly as it appears in the script?
Is the pronunciation entry active (not deleted)?
Is the agent using the correct voice/TTS provider?

Fix: Some TTS providers have different phoneme formats. Check provider documentation.

Pronunciation sounds worse than before

Problem: Phoneme format may be incompatible with TTS provider.Solution:

Try simplified phonetic spelling
Use common letter combinations
Test with shorter phonemes first

Only some words are fixed

Problem: Some words may be pronounced correctly by default.Solution: Focus on words that are actually mispronounced. Don’t fix what isn’t broken.

Agent says phoneme literally

Problem: TTS is reading the phoneme text instead of using it.Solution:

Check phoneme format (may need provider-specific format)
Ensure entry is saved correctly
Contact support if issue persists

TTS Provider Differences

Cartesia

Format: Simplified phonetic Example: koo-ber-net-eez Notes: Most flexible, handles simplified phonemes well

OpenAI TTS

Format: Simplified phonetic with some IPA support Example: ˈkuːbərˌnɛtiːz or koo-ber-net-eez Notes: Prefers simpler phonemes

ElevenLabs

Format: Context-aware (may not need explicit phonemes) Example: Often auto-corrects common words Notes: Best at inferring pronunciation from context

Deepgram

Format: Simplified phonetic Example: koo-ber-net-eez Notes: Similar to Cartesia

API Reference

List Pronunciations

GET /api/pronunciations/{agentId}
Authorization: Bearer YOUR_API_KEY

Create Pronunciation

POST /api/pronunciations/{agentId}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "word": "string (required)",
  "phoneme": "string (required)"
}

Update Pronunciation

PUT /api/pronunciations/{agentId}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "pronunciationId": "string (required)",
  "word": "string",
  "phoneme": "string"
}

Delete Pronunciation

DELETE /api/pronunciations/{agentId}?pronunciationId={id}
Authorization: Bearer YOUR_API_KEY

Bulk Import

POST /api/pronunciations/{agentId}/bulk
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "pronunciations": [
    {
      "word": "string",
      "phoneme": "string"
    }
  ]
}

Next Steps

Identify Problem Words

Test your agent and note any mispronunciations.

Create Pronunciations

Add custom pronunciations for your key terms.

Test & Iterate

Listen to output and adjust phonemes as needed.

​Overview

​Why Pronunciation Matters

​How It Works

​Step 1: Identify Problem Words

​Common Categories

​Testing for Mispronunciations

​Step 2: Create Pronunciation Entry

​Via Studio

​Via API

​Step 3: Writing Phonemes

​Phoneme Formats

​Phoneme Guidelines

Use Hyphens for Syllables

Spell Out Acronyms

Indicate Stress

Use Common Conventions

Test Iteratively

Keep It Simple

​Examples by Category

​Step 4: Manage Pronunciations

​List Pronunciations

​Update Pronunciation

​Delete Pronunciation

​Advanced Features

​Bulk Import

​Pronunciation Templates

​Case Sensitivity

​Best Practices

Start Small

Test with Real Audio

Document Your Choices

Update Regularly

Consider Your Audience

Be Consistent

​Troubleshooting

​TTS Provider Differences

​Cartesia

​OpenAI TTS

​ElevenLabs

​Deepgram

​API Reference

​List Pronunciations

​Create Pronunciation

​Update Pronunciation

​Delete Pronunciation

​Bulk Import

​Next Steps

Identify Problem Words

Create Pronunciations

Test & Iterate

Overview

Why Pronunciation Matters

How It Works

Step 1: Identify Problem Words

Common Categories

Testing for Mispronunciations

Step 2: Create Pronunciation Entry

Via Studio

Via API

Step 3: Writing Phonemes

Phoneme Formats

Phoneme Guidelines

Examples by Category

Step 4: Manage Pronunciations

List Pronunciations

Update Pronunciation

Delete Pronunciation

Advanced Features

Bulk Import

Pronunciation Templates

Case Sensitivity

Best Practices

Troubleshooting

TTS Provider Differences

Cartesia

OpenAI TTS

ElevenLabs

Deepgram

API Reference

List Pronunciations

Create Pronunciation

Update Pronunciation

Delete Pronunciation

Bulk Import

Next Steps