Talk API

The client contract for a live voice session — health, WebSocket, PCM audio, and events your app must handle. Not the thinking-layer API, and not operator admin.

Talk is the speech front door. A website or app opens one WebSocket, sends microphone audio, plays the reply, and handles a small set of JSON events. Cognition stays on the server; your client does not call the Reactive Agent.

Hostnames and credentials come with a pilot. Examples below use <talk-host> as a placeholder. Do not send operator tokens on this socket.

Minimum loop

GET /v1/health — connect only when status is "ok".
Open WS /v1/ws (use WSS when Talk is served over TLS).
Send microphone audio as 16 kHz mono 16-bit PCM binary frames (raw PCM, not a WAV container).
Play inbound binary as 24 kHz mono 16-bit PCM. Frames may be raw PCM or WAV-wrapped; if the first bytes are RIFF, strip the header and play the PCM.
Handle JSON events and plain-text playback commands (below).

JavaScript · connect

const health = await fetch("https://<talk-host>/v1/health").then((r) => r.json());
if (health.status !== "ok") throw new Error(health.status);

const ws = new WebSocket(
  "wss://<talk-host>/v1/ws?language=en&input_language=en&user=<stable-caller-id>"
);
ws.binaryType = "arraybuffer";

Health

GET /v1/health always returns HTTP 200 with a status field. Wait if the service is still starting; only open the WebSocket when status is ready.

JSON · ready

{
  "status": "ok"
}

If the socket is opened too early, Talk may close it. Unknown voice-profile identifiers also close the session. After a hang-up or transfer signal, the socket closes normally.

Session query

Pass identifiers Talk already knows. Omitted flags keep the profile (or process defaults).

Param	Role
`profile_id`	Voice profile for this session (listen / speak settings)
`language`	Spoken reply language
`input_language`	Listen language (defaults to the reply language)
`user`	Stable caller id if the agent should recognise the same person across reconnects

First-class languages are English, Hong Kong Cantonese, and Mandarin. Use the codes issued with your deployment.

Events the client must handle

Set binaryType = "arraybuffer". On text frames, try JSON parse; if that fails, treat the frame as a playback command.

Transcripts

JSON · transcript

{ "type": "transcript", "role": "user", "text": "…" }
{ "type": "transcript", "role": "assistant", "text": "…" }

The assistant transcript arrives before that turn's audio.

Hang-up and transfer

JSON · signal

{ "type": "signal", "action": "hangup" }
{ "type": "signal", "action": "transfer", "target": "<queue-or-destination>" }

signal is never spoken. Play any audio already in flight, then end or transfer the call as your channel requires. The socket may close after the signal.

Website chrome

Some sessions also send type: "ui" for on-screen forms or media. Render those in the page. Do not read them aloud. Form submit stays in your website — it is not a Talk API call.

Playback commands

If Talk sends CLEAR_BUFFER (or a flush command), stop local playback immediately and drop queued audio. That is how barge-in works on the client: the caller interrupts, Voice stops speaking, and your player must stop too.

Not this API

Data Nexus registry and proxy — see the Service SDK
Reactive Agent HTTP — Talk calls it; your app does not
Operator admin (profiles, cloned voices) — issued in a pilot, never in a public frontend

Related: How it works · Skill SDK · Request pilot access for operator manuals.