WebSocket API

const agentId = "agent_Fo7pKNBUwLZxrTd6jvhpaE";
const accessToken = "<token from POST /access-token>";

const ws = new WebSocket(
  `wss://api.cartesia.ai/v1/agents/websocket/${agentId}` +
    `?cartesia_version=2026-08-14&access_token=${accessToken}`
);

let ready = false;

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "session_create",
    audio: {
      input_format: "pcm_44100",
      output_delivery: "speaking_pace",
    },
  }));
};

ws.onmessage = (message) => {
  const event = JSON.parse(message.data);

  if (event.type === "session_ready") ready = true;
  if (event.type === "audio_output") playAudio(atob(event.audio));
  if (event.type === "audio_output_clear") stopPlayback();
};

function sendAudio(base64Audio) {
  if (!ready) return;
  ws.send(JSON.stringify({ type: "audio_input", audio: base64Audio }));
}

// Connect these to your audio player.
function playAudio(pcmBytes) {}
function stopPlayback() {}

wss://api.cartesia.ai/v1/agents/websocket/{agent_id}?cartesia_version=2026-08-14

{
  "type": "session_create",
  "audio": {
    "input_format": "pcm_44100",
    "output_delivery": "speaking_pace"
  }
}

{
  "type": "session_ready",
  "call_id": "ac_gqkgRWUz2u64qFUjA1mZyr",
  "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
  "agent_version_id": "av_7Hq2mXbK9cLdNfPzR3tWvE",
  "audio": {
    "input_format": "pcm_44100",
    "output_delivery": "speaking_pace"
  }
}

{
  "type": "audio_input",
  "audio": "base64_encoded_audio_data"
}

{
  "type": "audio_output",
  "audio": "base64_encoded_audio_data"
}

{
  "type": "client_tool_call",
  "tool_call_id": "call_2b7e4f9a1c0d",
  "tool_name": "lookup_cart",
  "parameters": { "cart_id": "cart_456" },
  "expects_response": true
}

{
  "type": "client_tool_result",
  "tool_call_id": "call_2b7e4f9a1c0d",
  "result": "2 items in cart",
  "is_error": false
}