Session flow

This page walks through the Real-time API in its current production form: real-time transcription with manual turn-taking, combined with session- and turn-level contextual biasing.

The lifecycle of a session is:

1. Open the WebSocket connection and send start_session (optionally with session-level biasing).
2. For each user turn: send start_turn (optionally with biasing context), stream the audio, then send end_turn.
3. Receive turn_started, turn_partial, and turn_ended events from the server for that turn.
4. Repeat step 2 for every subsequent turn on the same connection.

Starting a sessionCopy Anchor Link

Start by opening the WebSocket with your API key for authentication (see the Connection and Authentication section for the endpoint and headers), then send a message to start the session:

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

• language: the language spoken by the user. Supported: fr, en, pt, de, es, it.
• turn_taking_mode: manual, where the client explicitly marks the start and end of every turn.
• sessionContext (optional): session-level facts and hints describing this session before anyone speaks — the caller's details, who they reached, the jargon of this conversation. They apply to every turn.

See the start_session reference for the full message schema, and the server's session_started acknowledgement.

Starting a turnCopy Anchor Link

Before the user speaks, send a start_turn message. From this point on, the engine transcribes the incoming audio for this turn.

You can attach a turnContext to bias recognition toward what you expect the user to say on this turn. Session-level values from sessionContext still apply; turn-level hints and facts are added on top. Unlike session context, this one is worth sending only when you can narrow down the answer — see Turn-level context.

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

When you have no idea what the user will say, omit turnContext entirely and the turn runs unbiased:

{
  "type": "start_turn"
}

See the start_turn reference for the full turnContext schema.

Streaming audioCopy Anchor Link

Once the turn has started, stream the user's audio as binary WebSocket frames. Audio must be 16 kHz mono int16 PCM. All other protocol messages (such as start_turn / end_turn) are sent as JSON text frames. See the audio bytes reference for the format and chunking details.

Receiving turn eventsCopy Anchor Link

When the turn begins, you receive a turn_started message:

{
  "type": "turn_started",
  "turnId": "123"
}

As the engine decodes audio, you receive incremental turn_partial events (the turn partials from the terminology):

{
  "type": "turn_partial",
  "turnId": "123",
  "transcript": "oui c'est bien",
  "turnAudioDuration": 2.3
}

Ending a turnCopy Anchor Link

When the user is done speaking, send end_turn:

{
  "type": "end_turn"
}

The server finalizes the transcription of the audio received so far and replies with a turn_ended event containing the final transcript:

{
  "type": "turn_ended",
  "turnId": "123",
  "kind": "end_of_utterance",
  "transcript": "oui c'est bien une Peugeot 3008",
  "turnAudioDuration": 4.7
}

From here, repeat the start_turn → stream audio → end_turn cycle for every subsequent turn on the same connection.

For a complete, runnable client that puts this all together, see the Stream a local audio file quickstart.