What custom vocabulary does
Speech recognition guesses words from sound. Names it has never seen get mapped to the nearest common word. "Ozempic" becomes "so simple." "DELT-450" becomes "dealt four fifty." Once the transcript is wrong, everything downstream is wrong: the LLM sees the wrong word, the reply is wrong, and post-call analysis extracts the wrong field.
Custom vocabulary is a list of words and phrases you hand the recogniser in advance. It biases the recogniser toward those strings when the audio is ambiguous. It does not force them and it does not teach the agent what they mean.
Where to set it
Dashboard, on the Finn itself: Identity → Custom Vocabulary. There is no API field for vocabulary in the documented endpoints, so this is a dashboard-only operation. See agents-identity for the other fields on that tab.
The field takes a list of strings:
["Acme", "FinnAI", "Ozempic", "DELT-450", "Doctor Patel"]
Vocabulary is part of the Finn's configuration, so it is versioned with the rest of it and rolls back with it. See agents-versioning.
What to put in it
| Category | Examples | Why the recogniser fails without it |
|---|---|---|
| Brand names | Acme, FinnAI, Razorpay | Invented spellings have no dictionary entry |
| Product SKUs | DELT-450, XR-12 | Letter-digit mixes get split into words |
| Drug and clinical terms | Ozempic | Rare, and misheard as common words |
| Place names | Local suburbs, streets, branch names | Regional names are outside the general model |
| Person names | Doctor Patel | Staff names callers say every call |
| Regulatory terms | Aadhaar, PAN card, GST | Region-specific, often absent from the base model |
Include the form callers actually say. If callers say "Delt four fifty" rather than reading the hyphen, add both DELT-450 and Delt 450.
What to leave out
Keep the list short and specific. Every entry raises the chance the recogniser hears that entry where it was not said.
- Do not add common words. Adding
rightorfourmakes the recogniser hallucinate them into ordinary speech. - Do not add whole sentences. The bias applies to short phrases; long strings rarely match.
- Do not add every product in your catalogue. Add the ones callers actually name out loud.
- Do not use it to teach facts. If the agent needs to know what
DELT-450is, that belongs in the knowledge base or the prompt (agents-prompting).
Language behaviour
Vocabulary entries accept words in any language, independent of the Finn's configured language. This matters when callers code-switch and drop an English brand name into a Hindi sentence. The entry is matched on sound, so a Hindi-language Finn still benefits from English brand entries.
Recognition quality sets the ceiling. Vocabulary improves borderline recognitions, it does not rescue a language whose base accuracy is poor. Tier 3 languages need clean audio before vocabulary helps at all. See agents-multilingual and agents-stt.
What will go wrong
| Symptom | Likely cause | Fix |
|---|---|---|
| Term still transcribed wrong | Caller says it differently to how you spelled it | Add the spoken variant as a second entry |
| Ordinary words replaced by a vocabulary term | List contains a short or common-sounding entry | Remove that entry |
| Agent says the name wrong when speaking | Vocabulary affects recognition only, not speech | Fix pronunciation in TTS settings, see agents-tts |
| Fix did not take effect on a live call | Changes apply to new calls only | Wait for in-flight calls to end |
| Term recognised in tests, missed on real calls | Phone audio is worse than your test audio | Test over a real call, not chat |
Testing on chat will not exercise vocabulary at all. Chat has no audio and no recogniser, so the transcript is whatever you typed. Use Test on Call to check a vocabulary change. See agents-testing.
A working loop
- Run calls and read the transcripts in call-logs.
- Note the exact wrong string the recogniser produced, not the word you expected.
- Add the intended term to Custom Vocabulary. If the wrong string suggests a different pronunciation, add that spoken form too.
- Save, then place a test call over the phone and say the term twice.
- Check the transcript. If the term is still wrong after two attempts, the audio or the language tier is the constraint, not the vocabulary list.
Vocabulary is a tuning step, not a setup step. Ship the Finn, collect real transcripts, and add entries against errors you have actually seen.