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 on a transcription configuration that supports vocabulary biasing. If you are not sure whether your account is enabled for dictionaries, contact Vocobase support.

V2 API (v2) only. These endpoints live under https://api.vocobase.com/api/v2 and are reached with a rg_live_... Bearer token.

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

Limit	Value
Dictionary name	1–100 characters, unique per account
Description	0–500 characters
Terms per dictionary	Unlimited
Combined characters across all dictionaries attached to one agent	10,000
Term length	No 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

Creation is agent-agnostic. POST /api/v2/dictionaries does not take an agent_id — dictionaries are reusable across agents. To make a dictionary actually bias an agent’s STT, attach it in a separate step with PUT /api/v2/agent/{agent_id}/dictionaries.

curl -X POST https://api.vocobase.com/api/v2/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"
    ]
  }'

const response = await fetch("https://api.vocobase.com/api/v2/dictionaries", {
  method: "POST",
  headers: {
    "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    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",
    ],
  }),
});
const { data: dictionary } = await response.json();
console.log(dictionary.id);

import requests

response = requests.post(
    "https://api.vocobase.com/api/v2/dictionaries",
    headers={
        "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
        "Content-Type": "application/json",
    },
    json={
        "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",
        ],
    },
)
dictionary = response.json()["data"]

{
  "success": true,
  "data": {
    "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"],
    "term_count": 5,
    "char_count": 52,
    "attached_agent_count": 0,
    "created_at": "2026-04-24T10:30:00.000Z",
    "updated_at": "2026-04-24T10:30:00.000Z"
  }
}

Terms are normalized server-side: whitespace is trimmed, empty strings are dropped, non-string entries are silently skipped, and the dedupe is case-insensitive but preserves the first-occurrence casing. Passing ["Vocobase", "vocobase", " Vocobase "] stores ["Vocobase"], and term_count reflects the normalized list.

A blank or whitespace-only description is stored as null.

Attach dictionaries to an agent

Attachment is a set-replace. PUT /agent/{agent_id}/dictionaries overwrites the agent’s entire dictionary set with the dictionary_ids array you send. There is no separate attach/detach endpoint — to add one, send the current ids plus the new one; to detach one, send the current ids minus the one to remove; to detach everything, send []. The swap is wrapped in a transaction, so the agent is never briefly in a partial state.

curl -X PUT https://api.vocobase.com/api/v2/agent/{agent_id}/dictionaries \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "dictionary_ids": [
      "d1234567-abcd-1234-abcd-123456789012"
    ]
  }'

await fetch(`https://api.vocobase.com/api/v2/agent/${agentId}/dictionaries`, {
  method: "PUT",
  headers: {
    "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    dictionary_ids: ["d1234567-abcd-1234-abcd-123456789012"],
  }),
});

import requests

requests.put(
    f"https://api.vocobase.com/api/v2/agent/{agent_id}/dictionaries",
    headers={
        "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
        "Content-Type": "application/json",
    },
    json={"dictionary_ids": ["d1234567-abcd-1234-abcd-123456789012"]},
)

{
  "success": true,
  "data": {
    "dictionaries": [
      {
        "id": "d1234567-abcd-1234-abcd-123456789012",
        "name": "Vocobase Product Catalog",
        "term_count": 5,
        "char_count": 52,
        "attached_agent_count": 1,
        "created_at": "2026-04-24T10:30:00.000Z",
        "updated_at": "2026-04-24T10:30:00.000Z"
      }
    ]
  }
}

Every id in dictionary_ids must exist and belong to the calling account; otherwise the whole request fails with 400 VALIDATION_ERROR. Duplicate ids are deduped silently. If the combined char_count across the requested set would exceed 10,000 characters, the request fails with 400 DICTIONARY_CHAR_LIMIT_EXCEEDED:

{
  "success": false,
  "error": {
    "code": "DICTIONARY_CHAR_LIMIT_EXCEEDED",
    "message": "Attaching these dictionaries would exceed the 10,000-character limit for this agent.",
    "details": {
      "current_chars": 11240,
      "limit_chars": 10000
    }
  }
}

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.

Manage dictionaries

Dictionaries are ordinary CRUD resources — see the API Reference for full schemas.

Do this	Endpoint
List your dictionaries (summary shape, no `terms`)	`GET /dictionaries`
Get one, including `terms`	`GET /dictionaries/{id}`
Update `name`, `description`, or `terms`	`PATCH /dictionaries/{id}`
Delete	`DELETE /dictionaries/{id}`
List an agent’s attached dictionaries	`GET /agent/{id}/dictionaries`
Replace an agent’s attached set	`PUT /agent/{id}/dictionaries`

Four behaviours that are easy to get wrong:

terms replaces the whole list. There is no incremental add or remove. Merge client-side, then send the full array.
Updates are validated against every agent. If the new char_count would push an attached agent over the 10,000-character combined limit, the request fails with 400 DICTIONARY_CHAR_LIMIT_EXCEEDED and the details name the offending agent_id.
Changes apply to the next session. In-flight calls keep the snapshot taken when they started.
Deleting detaches everywhere. DELETE /dictionaries/{id} returns 204 No Content and removes the dictionary from every agent it was attached to. Nothing else is touched.

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

Symptom	Likely cause
Transcripts still wrong after attaching	Dictionary not yet effective on this call — dictionaries apply at session start. Start a new call.
`400 DICTIONARY_CHAR_LIMIT_EXCEEDED` on attach or update	This agent’s combined term characters would exceed 10,000. Detach something else or split the dictionary. Check `error.details` for the offending `agent_id` and `current_chars`.
`400 VALIDATION_ERROR` on `PUT /agent/{id}/dictionaries` with message “One or more dictionary_ids do not exist or are not owned by you”	One of the ids you sent is either wrong or belongs to another account. The whole request is rejected; fix the list and retry.
Dictionary has no effect on accuracy	Your account or agent may not be using a transcription configuration that supports dictionaries. Contact Vocobase support to verify.
`409 DICTIONARY_NAME_TAKEN` on create or update	Dictionary names must be unique per account. Rename or update the existing one.

Getting Started

Building Agents

Making Calls

Receiving Calls

After the Call

Telephony Providers

Advanced

API Reference

Endpoints

Speech Recognition Dictionaries

Speech Recognition Dictionaries

When dictionaries help most

Limits

Create a dictionary

Attach dictionaries to an agent

Manage dictionaries

Tips for authoring good dictionaries

Troubleshooting

​Speech Recognition Dictionaries

​When dictionaries help most

​Limits

​Create a dictionary

​Attach dictionaries to an agent

​Manage dictionaries

​Tips for authoring good dictionaries

​Troubleshooting

Speech Recognition Dictionaries

When dictionaries help most

Limits

Create a dictionary

Attach dictionaries to an agent

Manage dictionaries

Tips for authoring good dictionaries

Troubleshooting