Contextual biasing

Contextual biasing lets you tell the engine what to expect before it produces a transcript. Both APIs accept it, in the same shape, but at different levels:

• The Real-time API has two levels: sessionContext on start_session, which applies to every turn in the session, and turnContext on start_turn, which is added on top for that turn only.
• The Sync API has one: the context field of the config part. A request carries one audio file with no session around it, so there is nothing to separate.

Facts and hintsCopy Anchor Link

Both APIs take facts, hints, or both.

facts are named values the engine should know about - who is on the call, what they are calling about, which product or account is in play. Each fact is an object with:

• name (required): a label for the fact.
• value (required): the fact value used for biasing.
• description (optional): a description to help the engine interpret the value.

hints are the values you expect to actually be spoken. Each hint is an object with:

• type (required): values.
• values (required): a list of strings the user is expected to say. These bias the recognizer toward those outputs.
• name (optional): a label for the hint.
• description (optional): a description to help the engine interpret the values.

Session-level contextCopy Anchor Link

Session context grounds the whole conversation. Send it once on start_session, with what you already know about this particular session before anyone has spoken:

• Who the caller is: their name, account or customer id, city, the vehicle or policy or order the call is about.
• Who or what they reached: the agent's name, the service or product line, the brand.
• The jargon of this conversation: the vocabulary, product names, codes and abbreviations that are normal in this context and rare everywhere else.

These values apply to every turn, so they are worth setting whenever you have them. Unlike turn context, session context is useful even when you have no idea what the user will say next — it is describing the world the conversation happens in, not predicting an answer.

{
  "type": "start_session",
  "language": "fr",
  "sessionContext": {
    "facts": [
      { "name": "customerName", "value": "Jean Dupont" },
      { "name": "callReason", "value": "révision annuelle" }
    ],
    "hints": [
      {
        "type": "values",
        "name": "carBrand",
        "values": ["Renault", "Peugeot", "Citroën", "Toyota", "Volkswagen"]
      }
    ]
  }
}

Turn-level contextCopy Anchor Link

Turn context help improve the accuracy of the next answer. Send it on start_turn, and only when you can actually narrow down what is coming.

It helps most in elicitation settings, where the answer is short and drawn from a finite, known set of values — the user is essentially picking from a preset list. Typical cases:

• Constrained answers: the response comes from a fixed set of options, such as a menu of choices, a yes/no confirmation, or an expected number like a year.
• Niche or specific vocabulary: brand names, product codes, place names, proper nouns, or domain jargon that a general model may mis-transcribe.

It offers little to no benefit for open-ended, long-form, or unpredictable speech. When you have just asked "what can I help you with?", omit turnContext and let the turn run unbiased or with your session context only.

{
  "type": "start_turn",
  "turnContext": {
    "hints": [
      {
        "type": "values",
        "name": "carModel",
        "values": ["208", "2008", "3008", "5008"]
      }
    ]
  }
}

On the Sync APICopy Anchor Link

A sync request has no session around it, so its single context carries both jobs at once: the facts that ground the recording, and the values you expect to hear in it.

{
  "language": "fr",
  "context": {
    "facts": [
      { "name": "customerName", "value": "Jean Dupont" }
    ],
    "hints": [
      {
        "type": "values",
        "name": "carModel",
        "values": ["208", "2008", "3008", "5008"]
      }
    ]
  }
}