TypeScript realtime

Mint with kupe.realtime.sessions.create, then kupe.realtime.connect(session). Audio is PCM16 mono 24 kHz. Model kupe-realtime. Web-only — no telephony minutes. Identify the agent with name or agent_id. A new name creates the agent with prompt, greeting, voice, and tools/mcp. Pass voice (sanitized name) or voice_id — either one (copy the id from the voice library).

Terminal

Node 18+ (ESM). From a folder where kupe-sdk is installed:

npm install kupe-sdk
export KUPE_API_KEY=sk-kupe-YOUR_KEY
node --input-type=module <<'EOF'
import { Kupe } from "kupe-sdk";

const kupe = new Kupe();
const session = await kupe.realtime.sessions.create({
  name: "Priya",
  voice: "priya",
  prompt: "You collect overdue EMIs. Be warm and brief.",
  greeting: "Hi, this is Priya from the bank.",
});
console.log("ws", session.websocket_url);

const rt = await kupe.realtime.connect(session);
rt.sendText("Remind them EMI is due tomorrow.");
for await (const event of rt) {
  if (event.type === "response.output_audio_transcript.done") {
    console.log("agent:", event.transcript);
    rt.close();
    break;
  }
  if (event.type === "error") {
    console.error("error:", event);
    rt.close();
    break;
  }
}
EOF

File form (realtime.mjs):

import { Kupe } from "kupe-sdk";

const kupe = new Kupe();
const session = await kupe.realtime.sessions.create({
  name: "Priya",
  voice: "priya",
  prompt: "You collect overdue EMIs. Be warm and brief.",
  greeting: "Hi, this is Priya from the bank.",
});
const rt = await kupe.realtime.connect(session);
rt.sendText("Remind them EMI is due tomorrow.");
for await (const event of rt) {
  if (event.type === "response.output_audio_transcript.done") {
    console.log("agent:", event.transcript);
    rt.close();
    break;
  }
}

node realtime.mjs

Events you will see

`event.type`	Meaning
`session.created`	Handshake done
`response.output_audio.delta`	Base64 PCM16 chunk
`response.output_audio_transcript.done`	Final spoken text (`event.transcript`)
`response.done`	Turn finished, includes usage
`error`	Protocol or runtime error

sendText / send_text send conversation.item.create then response.create. Mic path: rt.appendAudio(pcm16) at 24 kHz.

Echo: speakers vs headset

If you play the agent’s audio through open speakers next to the mic, the mic records the agent and appendAudio sends its own voice back as user speech. The agent then answers itself, and its greeting shows up in the transcript as a user turn. Pass echoSuppression: "half_duplex" to mute the mic while the agent is still speaking:

const rt = await kupe.realtime.connect(session, { echoSuppression: "half_duplex" });

rt.appendAudio(pcm16); // sent as silence while the agent talks

Option	Use when	Barge-in
`"none"` (default)	Headset, phone line, or a browser `getUserMedia({ echoCancellation: true })` stream — echo is already cancelled	Yes
`"half_duplex"`	Open speakers, e.g. a Node script on a laptop	No — the server does not hear you until the agent stops

appendAudio returns true when the chunk was sent and false when it was muted; rt.suppressedChunks counts the muted chunks, and rt.agentIsSpeaking exposes the gate. Pass { force: true } to bypass it for one chunk. Tune the hold after playback ends with echoTailMs (default 250). A muted chunk is still sent, as silence. The server runs streaming VAD and STT over a continuous audio stream, so sending nothing at all would stall turn detection and the agent would stop hearing you even after it stopped talking.

In the browser you normally want the default "none": request the mic with getUserMedia({ audio: { echoCancellation: true } }) and the browser cancels the echo for you, keeping barge-in working.

Full event tables: Realtime WebSocket.

​Terminal

​Events you will see

​Echo: speakers vs headset

Terminal

Events you will see

Echo: speakers vs headset