Context
Learn how to use custom context to enhance transcription accuracy.
Overview
Context tells the model what to expect before it starts listening: what the audio is about, which names and words are likely to come up, and how you spell them. It improves transcription of names and special words, and lets you control how terms are translated.
Here's the context a physiotherapy clinic sends with every call to its phone agent. The rest of this page uses the same clinic to explain each part.
How context works
You send context once, when the session starts, and it's used for the whole session.
Context gives the model hints about what it's likely to hear. When a word in the audio could be one of your terms, the model leans toward your term and your spelling.
- The model uses one of your terms only when it fits the rest of the sentence. If an everyday word that sounds similar fits better, the model writes the everyday word.
- Words and names you didn't list are still transcribed as usual.
- You don't need a perfect context. It's fine if most of your terms are never said, or if some words are missing.
Unusual names benefit the most
If the model doesn't know a name, it may spell it wrong the first time and keep
that spelling for the rest of the session. Add the name to terms to avoid this.
What to put in each section
The context object has four sections. All of them are optional, so use the ones that fit your data.
You don't need to repeat things across sections: if your staff are already listed in text,
use terms only for the words that aren't there.
| Section | Type | Use it for |
|---|---|---|
general | array of key-value pairs | A few short facts: domain, topic, names, location, people |
text | string | Longer background: a description, a document or a data sheet |
terms | array of strings | Words and names you want spelled your way |
translation_terms | array of source-target pairs | How specific words should be translated |
General
A few short facts that tell the model what the audio is about, so it knows which words to expect.
Add the domain or topic, like domain: physiotherapy or topic: appointments and sports injuries.
Names alone often don't say what the conversation is about. A business called "ACME Group" or "JTS"
could be anything, so the domain is what tells the model the setting.
Also good to add: the business or product name, the agent's name, the location, and the names of people who are likely to come up.
Keep in mind:
- We recommend 2 to 8 pairs.
- Keep keys to a few words, and values to a name or short label, not a sentence.
- Name keys however you like (
business name,business_name,businessName), just stay consistent.
Text
Longer background, written however you like. It helps most when it mentions the same names and words that come up in the audio.
Good to add:
- A short description of what the conversations are about.
- Text you already have, like an FAQ, policies, part of your agent's instructions, or notes from earlier conversations.
- A data sheet: your data grouped under headings, like staff and their roles, locations and their addresses, services or opening hours. The layout doesn't matter much; headings and simple lists work fine.
For example, a data sheet like this:
is sent as a single string:
A data sheet can be long, like every branch or your whole menu, as long as the context stays under the size limit.
Terms
A list of words and names you want recognized and spelled your way. This is the most direct way to fix names and special words.
Good to add:
- Names of people, places, streets and branches.
- Your own brand, product, plan and service names.
- Special words and abbreviations of your field, like
dry needling,KubernetesorHVAC. - Other spellings people use, like
call backandcallback.
Leave out:
- Common words like
appointment, even if they come up all the time, and names everyone knows, like Google or Coca-Cola. - Sentences. Keep each term to a few words.
- Numbers, codes, dates, prices, email addresses and phone numbers.
You only need one form of each word, since dry needling also helps with "dry needlings".
Capitalization matters, though: the model writes a term the way you list it, so write names, brands and
acronyms with the capitals you want, like Pilates, iPhone or HVAC.
Order doesn't matter, and long lists are fine.
Translation terms
Tell the model how specific words should be translated. Use this only for translation;
for transcription, use terms.
To keep a name unchanged in the translation, map it to itself.
Common setups
Voice agents
Write the context once for each agent and send it with every call. It should describe your business and the usual reasons people call, not a specific call. Update it when your details change, like new staff or services. Don't build it from recordings of past calls, and don't try to guess the exact sentences callers will say.
On top of that, for each call:
- Add what you know about the caller. If you know who is calling before the call starts, for example from your CRM or a signed-in account, add their name and details. Only add what's on file, not answers you expect them to give. If something is out of date and the caller corrects it, the transcript shows what they actually said.
- Set language hints to the languages your agent supports. Other languages are still recognized, and a short list works better than a long one.
- Send what the agent says with agent text input. Context covers your business for the whole call, and agent text tells the model what the user is replying to.
Recordings and meetings
When you transcribe a recording, you often know more about it in advance: who is speaking and what it's about. Add that to the context for that recording.
Personal assistants
For a smart speaker, car or device assistant, there's no business to describe. Build the context for each user from their own data instead: their name, family members, contacts, room and device names, playlists and saved places.
Other languages
Write the context in the language people speak. Keys can stay in English if that's easier for your code, but don't translate your data. Names, products and places should be written the way people say them. In languages with their own script, like Korean, write local names in that script and keep brand names as they're usually written.
If people speak more than one language, or mix them like Hindi and English, your terms can be in different languages too. List each term in the language and script people will say it in.
Checklist
general: domain or topic, business or product name, agent name, location, people. 2 to 8 pairs.terms: every unusual name, plus your services, places, brands and special words.text(optional): a short description, a document you already have, or a data sheet.- For voice agents: the caller's details and language hints for each call.
- The whole context stays under the size limit.
Context size limit
- Maximum 8,000 tokens (about 10,000 characters).
- If you go over, the API returns an
invalid_requesterror. Trim long lists to the items people actually mention, and summarize long documents.


