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 Session flow.

start_turn (Client to Server message)Copy Anchor Link

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): turn-level contextual biasing — what you expect the user to say on this turn. Values here are added on top of any session-level sessionContext, which still applies. It contains:
  • facts (optional): a list of named values the engine should know about for this turn. 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 (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.

Turn context pays off when the answer is short and drawn from a known list, and does little for open-ended speech — send it only when you can actually narrow down what is coming. See Turn-level context for the details, and Session-level context for the values that are worth setting once for the whole session instead.

Example (no biasing):

{
  "type": "start_turn"
}

Example (biasing toward expected values):

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

end_turn (Client to Server message)Copy Anchor Link

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"
}