Skip to main content

​
Speech Recognition Dictionaries

Dictionaries are short lists of domain-specific terms — brand names, product SKUs, technical jargon, people, places — that you attach to an agent. The speech-to-text engine biases its transcription toward those terms, so the agent hears “Vocobase” instead of “Vocal base” and “SKU-4471” instead of “skew four thousand four hundred seventy one”.
Dictionaries only affect agents using the Soniox STT provider, which is the default for new agents. They have no effect on other providers.

​
When dictionaries help most

  • Proper nouns the model has never seen (your company name, product names, internal codes)
  • Ambiguous homophones where context alone does not disambiguate (e.g., “Mira” vs “Meera”)
  • Alphanumeric identifiers the user speaks slowly (serial numbers, reference codes)
  • Non-English-origin words embedded in an English call (e.g., Indian names, Spanish towns)
They do not help with:
  • Accent adaptation (that is handled by the language model itself)
  • Entire sentences or long phrases (dictionaries are a per-term bias, not a grammar)
  • Replacing STT output with a canonical form (use your own post-processing for that)

​
Limits

LimitValue
Dictionary name1–100 characters, unique per partner
Description0–500 characters
Terms per dictionaryUnlimited
Combined characters across all dictionaries attached to one agent10,000
Term lengthNo hard limit; short phrases (1–4 words) work best
The 10,000-character cap is enforced at attachment time and on PATCH, so you cannot accidentally push an agent over the limit.

​
Create a dictionary

curl -X POST https://api.vocobase.com/api/dictionaries \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vocobase Product Catalog",
    "description": "Product names, SKUs, and plan tiers referenced on support calls.",
    "terms": [
      "Vocobase",
      "SKU-4471",
      "Pro Annual Plan",
      "Voice Sandbox",
      "Meera Iyer"
    ]
  }'

{
  "id": "d1234567-abcd-1234-abcd-123456789012",
  "name": "Vocobase Product Catalog",
  "description": "Product names, SKUs, and plan tiers referenced on support calls.",
  "terms": ["Vocobase", "SKU-4471", "Pro Annual Plan", "Voice Sandbox", "Meera Iyer"],
  "termCount": 5,
  "charCount": 52,
  "createdAt": "2026-04-24T10:30:00Z",
  "updatedAt": "2026-04-24T10:30:00Z"
}
Terms are case-insensitive and deduplicated server-side, so "vocobase" and "Vocobase" count as one. Passing the same term twice does not inflate termCount.

​
Attach a dictionary to an agent

An agent can have any number of dictionaries attached; all of their terms are merged at session start. 
curl -X POST https://api.vocobase.com/api/agents/{agent_id}/dictionaries \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{ "dictionary_id": "d1234567-abcd-1234-abcd-123456789012" }'
If attaching a dictionary would push the agent’s combined term characters past 10,000, the request fails with 400 DictionaryCharLimitExceeded. Detach a less-relevant dictionary, or split a large dictionary into smaller, more targeted ones.
Bigger is not better. A focused 200-term dictionary biases the STT engine more effectively than a 2,000-term grab-bag because the engine has fewer distractors to weigh. Keep dictionaries narrow.

​
Update a dictionary

PATCH any subset of name, description, or terms. Passing terms replaces the whole list — there is no incremental add/remove. Merge the lists client-side before sending. 
curl -X PATCH https://api.vocobase.com/api/dictionaries/d1234567-abcd-1234-abcd-123456789012 \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "terms": ["Vocobase", "SKU-4471", "SKU-4472", "Pro Annual Plan"]
  }'
Changes take effect on the next session that starts. In-flight calls continue with the snapshot taken at session start.

​
Delete a dictionary

curl -X DELETE https://api.vocobase.com/api/dictionaries/d1234567-abcd-1234-abcd-123456789012 \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"
Returns 204 No Content. The dictionary is removed and detached from every agent it was attached to.

​
Tips for authoring good dictionaries

  • Write terms the way they are pronounced, not the way they are written. If your product “GraphQL” is pronounced “graph Q L”, add both GraphQL and graph Q L.
  • Group by domain, not by size. One dictionary per product line, region, or use case is more useful than one mega-dictionary.
  • Audit with real transcripts. Pull a week of call recordings and look for consistent mis-transcriptions — those are your dictionary candidates.
  • Remove, don’t just add. Terms that never appear in your actual conversations add noise. Trim after two weeks of usage.

​
Troubleshooting

SymptomLikely cause
Transcripts still wrong after attachingDictionary not yet effective on this call — dictionaries apply at session start. Start a new call.
400 DictionaryCharLimitExceeded on attachThis agent’s combined term characters would exceed 10,000. Detach something else or split the dictionary.
Dictionary has no effect on accuracyYou are likely not using the Soniox STT provider. Only Soniox supports biased transcription; other providers ignore attached dictionaries.
409 on createDictionary names must be unique per partner. Rename or update the existing one.