Skip to content
Introducing STTv6See what's new
Speech-to-TextFeaturesAccuracy

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.

{
  "context": {
    "general": [
      { "key": "business name", "value": "Cootamundra Physiotherapy and Sports Injury Clinic" },
      { "key": "agent name",    "value": "Lina" },
      { "key": "domain",        "value": "physiotherapy" },
      { "key": "location",      "value": "Cootamundra NSW" },
      { "key": "people",        "value": "Bill Campbell, Jerome Santos, Jean Hall" }
    ],
    "text": "Callers book, move and cancel appointments and ask about prices.\n\n## Services\n- Initial consultation\n- Standard follow-up - 30 minutes\n- Dry needling\n- Sports massage\n- Pilates class",
    "terms": [
      "Wallendoon Street",
      "Temora",
      "Medicare",
      "chronic condition plan",
      "dry needling"
    ]
  }
}

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.

SectionTypeUse it for
generalarray of key-value pairsA few short facts: domain, topic, names, location, people
textstringLonger background: a description, a document or a data sheet
termsarray of stringsWords and names you want spelled your way
translation_termsarray of source-target pairsHow 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.
"general": [
  { "key": "business name", "value": "Cootamundra Physiotherapy and Sports Injury Clinic" },
  { "key": "domain",        "value": "physiotherapy" },
  { "key": "location",      "value": "Cootamundra NSW" }
]

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:

## Staff
- Bill Campbell - principal physiotherapist
- Jerome Santos - sports injuries
- Jean Hall - reception

## Locations
- Wallendoon Street clinic: 120 Wallendoon Street, Cootamundra
- Temora rooms: Tuesdays only

## Hours
Monday to Friday 8:00 to 18:00, Saturday 8:00 to 12:00

is sent as a single string:

"text": "## Staff\n- Bill Campbell - principal physiotherapist\n- Jerome Santos - sports injuries\n- Jean Hall - reception\n\n## Locations\n- Wallendoon Street clinic: 120 Wallendoon Street, Cootamundra\n- Temora rooms: Tuesdays only\n\n## Hours\nMonday to Friday 8:00 to 18:00, Saturday 8:00 to 12:00"

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, Kubernetes or HVAC.
  • Other spellings people use, like call back and callback.

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.

"terms": ["Wallendoon Street", "Temora", "Medicare", "chronic condition plan", "dry needling", "Pilates"]

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.

"translation_terms": [
  { "source": "dry needling",  "target": "punción seca" },
  { "source": "follow-up",     "target": "consulta de seguimiento" },
  { "source": "Bill Campbell", "target": "Bill Campbell" },
  { "source": "Medicare",      "target": "Medicare" }
]

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.
{
  "language_hints": ["en", "tl"],
  "context": {
    "general": [
      // ...your business pairs
      { "key": "caller",  "value": "David Navarro" },
      { "key": "on file", "value": "Medicare chronic condition plan referral received" }
    ]
    // ...text and terms as before
  }
}

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.

"general": [
  { "key": "setting",         "value": "Recorded physiotherapy consultation" },
  { "key": "physiotherapist", "value": "Jerome Santos" },
  { "key": "patient",         "value": "David Navarro" },
  { "key": "topic",           "value": "Knee injury follow-up" }
]

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.

"general": [
  { "key": "business name", "value": "Datová kancelář" },
  { "key": "location",      "value": "Pardubice" },
  { "key": "people",        "value": "Marek Bureš, Pavlína Pecková" }
],
"terms": ["Roční platba", "Ceny bez DPH", "IČO", "Párování plateb", "Skladové karty"]

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

  1. general: domain or topic, business or product name, agent name, location, people. 2 to 8 pairs.
  2. terms: every unusual name, plus your services, places, brands and special words.
  3. text (optional): a short description, a document you already have, or a data sheet.
  4. For voice agents: the caller's details and language hints for each call.
  5. 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_request error. Trim long lists to the items people actually mention, and summarize long documents.

On this page