WebSocket channel
Behind every Delphi browser session runs a WebSocket channel between the client and the platform. It carries chat turns, session control messages, tool-call requests, transcripts, and runtime updates. For voice sessions, WebRTC media rides alongside the channel; for text sessions (mode: text), the channel is the entire transport — no SIP leg.
If you use the client SDK, you never see this channel directly — the SDK opens it, parses it, and gives you a higher-level API. This page documents the concept so you know what's going on under the hood, and so you can debug when something doesn't add up.
Why a WebSocket
REST is fine for "do a thing and tell me when you're done". A live conversation needs:
- Bi-directional streaming (the platform pushes transcript updates, the client pushes control inputs).
- Sub-second latency for tool callbacks and turn detection.
- Long-lived sessions that survive network blips.
A persistent WebSocket is the simplest fit; it keeps the connection open for the lifetime of the session.
Where the channel fits
- The client opens the session with a call token (for WebRTC) or directly with the SDK's session API (for other modes — see SDK sessions and modes).
- The platform routes the channel to the conversation engine running the relevant flow.
- WebRTC media is negotiated alongside the channel where applicable; the channel itself stays alive as the control plane.
What rides on it
| Direction | Examples |
|---|---|
| Client → server | Text chat (chat), browser context, control (text-chat enable, response mode), browser-action acks, manual hang-up. |
| Server → client | Assistant chat, transcript deltas, tool-call envelopes, TTS audio chunks (audio_playback), runtime status, session end. |
For browser TTS/read-aloud, current platforms stream audio as a start event, one or more delta chunks, and a done event. Clients should not assume the complete audio payload arrives in one message.
The full message catalogue lives in the SDK reference under Channel protocol. That page is the authoritative one for message shapes — they evolve with each SDK release.
When you might speak to it directly
Almost never. Reasons you might:
- You're writing a non-SDK client for a platform the SDK doesn't ship for. In that case, work from the SDK's source as the reference implementation.
- You're debugging an SDK-platform mismatch and want to look at the wire to confirm what's going past the SDK.
In both cases, the SDK source under the public client SDK is the only public source-level reference. Do not pin against an unpublished protocol version — see Compatibility.
See also
- SDK overview — the typed client to use instead of speaking to the channel directly.
- Channel protocol — exhaustive message catalogue.
- Text chat — pure text sessions and upgrade/downgrade.
- Sessions and modes — the SDK's session abstraction over the channel.