API Overview
Messages exchanged between client and server over the WebSocket connection.
This section documents the messages exchanged between client and server over the WebSocket connection. The current production API runs in manual turn-taking mode: the client explicitly brackets each turn with start_turn and end_turn. If you are new here, read the High-Level Flow first for the end-to-end walkthrough, then use this reference for the exact schemas.
You can also refer to the Stream a local audio file quickstart for a practical python integration of the API.
The reference is split into four pages, grouped by concern. Client Session API and Client Turn Control API cover the client-driven (Client → Server) messages; Server API and Error Management cover the server-driven (Server → Client) messages. Each message in the tables below links to the page that documents it.
Messages
Client → Server (JSON text frames, plus binary audio frames):
| Message | Type | Purpose | Documented in |
|---|---|---|---|
start_session | JSON | First message; sets language and turn-taking mode. | Client Session API |
| audio bytes | raw | Binary frames of 16 kHz mono int16 PCM audio for the active turn. | Client Session API |
start_turn | JSON | Marks the start of a turn; optionally carries turn-level biasing (turnContext). | Client Turn Control API |
end_turn | JSON | Marks the end of the current turn. | Client Turn Control API |
Server → Client (JSON text frames):
| Message | Type | Purpose | Documented in |
|---|---|---|---|
session_started | JSON | Acknowledges the session and returns its id. | Server API |
turn_started | JSON | A turn has started. | Server API |
turn_partial | JSON | Incremental transcript decoded so far. | Server API |
turn_ended | JSON | The turn ended; contains the final transcript. | Server API |
error | JSON | An error occurred; the connection is closed afterwards. | Error Management |