> ## Documentation Index
> Fetch the complete documentation index at: https://docs.callers.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Speech recognition vocabulary

> Improve how accurately your agent understands brand names, product terms, and other uncommon words, in the dashboard or through the API.

Speech recognition is very good at everyday words but can mishear brand names, product codes, surnames, and jargon. Adding these words to the agent's vocabulary makes recognition more reliable, which means more accurate transcripts, fewer misunderstandings, and better post-call analysis.

The vocabulary changes only how the agent **hears**. To change how the agent **says** a word, use the [Pronunciation dictionary](https://docs.callers.ai/documentation/voice/pronunciation-dictionary.md).

## What to add

Good candidates:

* Your company, product, and plan names (for example `Callers`, `ProMax 300`).
* Competitor names that contacts may mention.
* Industry terms and acronyms (`HVAC`, `APR`, `escrow`).
* Local place names and street names in your service area.
* Words the transcript gets wrong repeatedly. Check transcripts from test calls and real calls to find them.

You don't need to add common words, and you don't need to add each contact's name: Callers automatically adds useful words from the contact's [variables](https://docs.callers.ai/documentation/build-your-agent/agent-variables.md), such as names and company names, to the vocabulary for that call.

## Add vocabulary in the dashboard

Open the agent and click **Agent** in the editor header. There are two sections for this:

### Speech Recognition Vocabulary

Use this section to add words and how they may sound.

**1. Expand Speech Recognition Vocabulary**

It's in the agent's **Agent** settings (see [Agent settings](https://docs.callers.ai/documentation/build-your-agent/agent-setup.md#agent-voice-and-conversation)).

**2. Enter the word**

Type the word as it should appear in transcripts in **Word**.

**3. Add sound-alike variants (optional)**

In **Sounds like**, type how the word may be heard and press Enter. Add several variants, or paste a comma-separated list. For example, for `Callers` you might add `call ers` and `collars`.

**4. Add more words**

Click **Add word** for each additional entry, then save the agent.

> [!NOTE]
>
> If you don't see **Speech Recognition Vocabulary** in your agent, contact [support@callers.ai](mailto:support@callers.ai) to turn it on.

### Boost Keyword Recognition

**Boost Keyword Recognition** is a quick way to add single keywords. Type a **Keyword** and click **Enter**; the keyword is added to the agent's recognition vocabulary. The optional **Set Weight** field (−100 to 100) is kept for older agents; new agents should use **Speech Recognition Vocabulary**, which also supports sound-alike variants.

## Manage vocabulary with the API

Use the vocabulary endpoints to sync terms from your product catalog or CRM. Each agent holds up to 1,000 vocabulary entries; each entry can have up to 50 `sounds_like` variants.

| Method | Endpoint | What it does |
| - | - | - |
| `GET` | `/agents/{agentId}/vocabulary` | List all entries. |
| `POST` | `/agents/{agentId}/vocabulary` | Add entries. An entry with the same `content` as an existing one replaces it. |
| `PUT` | `/agents/{agentId}/vocabulary` | Update existing entries only. Entries with no matching `content` are ignored. |
| `POST` | `/agents/{agentId}/vocabulary/remove` | Remove the entries whose `content` matches the given `words`. |
| `DELETE` | `/agents/{agentId}/vocabulary` | Remove all entries. |

The legacy paths `/campaigns/{campaignId}/vocabulary` work the same way. Add the `x-sub-organization-id` header to act on an agent in a sub-account.

### Add entries

**vocabulary** `object[]` *required*

1–1,000 entries.

**properties**

**content** `string` *required*

The word or phrase as it should appear in transcripts.

**sounds\_like** `string[]`

Up to 50 ways the word may sound or be mis-heard.

```bash cURL theme={"dark"}
curl -X POST https://api.callers.ai/agents/AGENT_ID/vocabulary \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vocabulary": [
      { "content": "Callers", "sounds_like": ["call ers", "collars"] },
      { "content": "ProMax 300" }
    ]
  }'
```

```javascript Node.js theme={"dark"}
const response = await fetch(
  "https://api.callers.ai/agents/AGENT_ID/vocabulary",
  {
    method: "POST",
    headers: {
      Authorization: process.env.CALLERS_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      vocabulary: [
        { content: "Callers", sounds_like: ["call ers", "collars"] },
        { content: "ProMax 300" },
      ],
    }),
  }
);
const result = await response.json();
console.log(result.data.totalCount);
```

```python Python theme={"dark"}
import os
import requests

response = requests.post(
    "https://api.callers.ai/agents/AGENT_ID/vocabulary",
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
    json={
        "vocabulary": [
            {"content": "Callers", "sounds_like": ["call ers", "collars"]},
            {"content": "ProMax 300"},
        ]
    },
)
print(response.json()["data"]["totalCount"])
```

```json Response theme={"dark"}
{
  "status": "success",
  "data": { "success": true, "totalCount": 2 }
}
```

`totalCount` is the number of entries on the agent after the change. If the total would exceed 1,000 entries, the request fails with `400`.

### Remove entries

```bash cURL theme={"dark"}
curl -X POST https://api.callers.ai/agents/AGENT_ID/vocabulary/remove \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "words": ["ProMax 300"] }'
```

```javascript Node.js theme={"dark"}
await fetch("https://api.callers.ai/agents/AGENT_ID/vocabulary/remove", {
  method: "POST",
  headers: {
    Authorization: process.env.CALLERS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ words: ["ProMax 300"] }),
});
```

```python Python theme={"dark"}
requests.post(
    "https://api.callers.ai/agents/AGENT_ID/vocabulary/remove",
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
    json={"words": ["ProMax 300"]},
)
```

The response includes `removedCount`, the number of entries removed.

## Best practices

* **Keep the list focused.** A few dozen high-value terms work better than thousands of common words.
* **Write `content` exactly as you want it transcribed**, including capitalization and spacing.
* **Add sound-alikes from real transcripts.** When a word is mis-heard, add the wrong transcription as a `sounds_like` variant.
* **Review after changes.** Check transcripts from a few test calls after updating the vocabulary.

## Related

> **[Pronunciation dictionary](https://docs.callers.ai/documentation/voice/pronunciation-dictionary.md)**
>
> Control how the agent says words.

> **[Supported languages](https://docs.callers.ai/documentation/using-callers/supported-languages.md)**
>
> Pick the right dialect for accurate recognition.

> **[Voices and sounds](https://docs.callers.ai/documentation/voice/voices-and-sounds.md#noise-cancelation)**
>
> Reduce background noise.

> **[API introduction](https://docs.callers.ai/api-reference/introduction.md)**
>
> Authentication and response format.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.