Legacy browser JavaScript SDK (09/30/2026)

Migrate from the deprecated Retell AI browser client SDK v2 to v3: replace RetellWebClient with RetellClient and update call creation and event handlers.

Version 2.x of the browser JavaScript SDK, retell-client-js-sdk, will be deprecated on September 30, 2026. Upgrade to SDK 3.x and replace RetellWebClient with RetellClient for call creation, audio, and event handling. Existing integrations continue working during migration.

Upgrade the browser SDK

Upgrade to the latest browser SDK:

npm install retell-client-js-sdk@latest

SDK 3.x retains RetellWebClient for compatibility. Upgrading the package alone does not migrate your integration to RetellClient; update call creation and event handlers as shown below.

Replace call creation and connection

Replace the request to your server and RetellWebClient.startCall() with RetellClient.createWebCall(). The SDK sends the v3 request and connects audio automatically.

Create a public key and allow your website’s domain (localhost for local testing). Keep API keys on your server. If reCAPTCHA is enabled for the public key, pass a fresh token as recaptchaToken with each call.

Add call controls to your page:

<button id="start-call">Start call</button>
<button id="end-call">End call</button>

In your frontend JavaScript, replace the public key and agent ID with your own. Load this code after the buttons exist, using your frontend’s module bundler.

app.js

import { RetellClient } from "retell-client-js-sdk";

const client = new RetellClient({ key: "public_key_YOUR_PUBLIC_KEY" });
let call;

document.getElementById("start-call").addEventListener("click", () => {
  if (call && call.status !== "ended") return;

  call = client.createWebCall({
    agent_id: "agent_oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
    hooks: {
      onStatus: (status) => console.log("Call status:", status),
      onEnd: () => console.log("Call ended"),
      onError: (error) => console.error("Call error:", error),
    },
  });
});

document.getElementById("end-call").addEventListener("click", async () => {
  await call?.end();
});

Serve the page over HTTPS or on localhost, click Start call, and allow microphone access. Talk to the agent, then click End call. The session ends and fires onEnd. See the web call guide for audio controls and live transcripts.

Update event handlers

Calls created through v3 do not deliver every event from the previous connection type. Audit handlers as well as call creation:

Existing behavior	Migration
Call lifecycle handlers	Use onStatus, onEnd, and onError. Always reset the UI in onEnd, even when no error is reported.
update / onUpdate transcript updates	Enable transcript: true and use onTranscript. It receives merged transcript arrays; the old turntaking field is not supplied.
node_transition / onNodeTransition	With RetellClient, enable the transcript connection. Nodes from the initial snapshot also trigger the callback.
agent_start_talking, agent_stop_talking, or isAgentTalking	Use audio levels for visual activity estimates. Exact speaking boundaries and finalized-sentence events are not available.
metadata / onMetadata	No metadata event is delivered on the new connection. If you need the call’s stored metadata, retrieve it with Get Call.
audio / onAudio	Set audio.emitRawAudioSamples: true for visualization snapshots. These are not a continuous audio stream.

See the web call guide for supported hooks, transcript authentication, and audio options.

Related endpoint change for server-created calls

As part of this migration, POST /v2/create-web-call will also be deprecated on September 30, 2026 in favor of POST /v3/create-web-call. RetellClient.createWebCall() uses v3 automatically.

If you retain an existing server-created call flow, upgrade both your server SDK and browser SDK. The server SDK’s web-call creation method now uses v3 and returns connection details instead of the full call object. If you make HTTP requests directly, switch to POST /v3/create-web-call with the same JSON body.

Upgrade the browser SDK before switching the server to v3. For an existing RetellWebClient integration on SDK 3.x, forward these fields to startCall():

API response field	startCall() option
call_id	callId
access_token	accessToken
transport	transport
ice_servers	iceServers

Use get call if your application needs call fields such as call_status, agent_id, or metadata after creation.