Restricted Access: This panel and doc are internal-only. Global defaults change what the AI says on every org’s calls.
What this is
Every AI interview call applies a set of built-in default pronunciation rules on top of whatever rules an org configures for itself — things like TX → “Texas”, 401k → “four oh one K”, and HIPAA → “hippa”. These defaults were previously hardcoded in Python code and have now been seeded into the global_pronunciations database table.
The Internal Tools → Pronunciations panel makes that set editable at runtime. The database table is the single source of truth for global defaults across the system.
Internal Tools → Pronunciations (support/full-access users only).
The editor works exactly like the per-org pronunciation page: a Spelled as term, a Spoken as respelling, and a Match case toggle. Only the audio changes — transcripts, summaries, and notes keep the original spelling.
How resolution works
Resolution is fully database-driven:
- The
global_pronunciations database table is the source of truth for global defaults.
- If the table row is absent or a database error occurs, resolution fails soft to an empty list (no default dictionary).
- An org’s own custom rules always win over a default for the same term on conflict.
- Changes propagate to running backend processes within one cache TTL (60s).
Never expose the global set to customers
The global rules are org-agnostic and can name other customers’ brands and terms, so the list
itself is effectively an unofficial client list. Keep it internal:
- The per-org settings API returns only that org’s own rules, and the customer docs and settings
page deliberately say nothing about a built-in list. Don’t add one.
- Customers don’t need visibility into it. If a default mispronounces something for them, they add
their own rule for that term and it overrides ours — no support ticket, no disclosure.
Two important caveats
- Blast radius. A bad global rule degrades calls for every customer. Keep terms long and distinctive, and prefer Match case for short codes (e.g.
TX) so they never fire inside ordinary words. Some state codes that are also English words (OR, IN, ME, …) are deliberately excluded — adding one is possible but breaks calls that use the word normally.
- Orgs with their own rules don’t update retroactively. An org that saved its own pronunciations baked the previous defaults into its ElevenLabs dictionary at save time. Editing the globals does not rebuild those dictionaries; run the
backfill_pronunciation_defaults one-time job to refresh them.
Usage tracking
Below the editor, the Usage table shows how many recent calls actually said each global term, from the offline scan_pronunciation_usage job.
This measures opportunity, not confirmed pronunciation: ElevenLabs gives no per-rule firing feedback, so the job counts calls whose agent speech contained the term (agent speech keeps its original spelling). A term that never appears over a long window is a candidate for removal; a term that appears constantly clearly earns its place. Global rows slightly over-count, because an org that overrides a term still says it.
The scan records usage at both tiers in the pronunciation_usage table, distinguished by a level column:
level = 'global' (org_id NULL) — a default rule, counted across every org’s calls. This is what the panel shows.level = 'org' (org_id set) — an org’s own custom rule, counted only within that org’s calls.
Each scan writes the whole snapshot in one transaction (a full replace), so removed rules are pruned. Org-level usage is recorded and queryable now; it is not yet surfaced on the per-org settings page.
Run the scan from server/:
