Client Turn Control API

In manual turn-taking mode, the client explicitly controls when each turn starts and ends using start_turn and end_turn. The start_turn message also carries turn-level contextual biasing via turnContext. For where these fit in a session, see Starting a turn and Ending a turn in the High-Level Flow.

start_turn (Client to Server message)

Sent by the client to start a turn. From this point on, the speech recognition engine transcribes the incoming audio for this turn. (Audio sent before start_turn is not transcribed, see audio bytes.)

• type (required): start_turn
• turnContext (optional): contextual biasing for this turn. Declaring what you expect the user to say measurably improves accuracy in constrained settings. It contains:
  • hints (optional): a list of biasing hints. 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 for this turn.
    • name (optional): a label for the hint.
    • description (optional): a description to help the engine interpret the values.

When is contextual biasing useful?

Contextual biasing 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:

• Niche or specific vocabulary: brand names, product codes, place names, proper nouns, or domain jargon that a general model may mis-transcribe.
• 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.

It offers little to no benefit for open-ended, long-form, or unpredictable speech. In those cases, omit turnContext and let the turn run unbiased.

Example (no biasing):

{
  "type": "start_turn"
}

Example (biasing toward expected values):

{
  "type": "start_turn",
  "turnContext": {
    "hints": [
      {
        "type": "values",
        "name": "brand",
        "values": ["Renault", "Peugeot", "Citroën", "Toyota", "Volkswagen"]
      }
    ]
  }
}

end_turn (Client to Server message)

Send this message to end the current turn.

When the server receives this message, it sends a turn_ended message back to the client (see turn_ended Server → Client Message).

• type (required): end_turn

Example:

{
  "type": "end_turn"
}