> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retellai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={"dark"}
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](/accounts/public-keys) 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:

```html theme={"dark"}
<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.

```javascript app.js theme={"dark"}
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](/deploy/web-call) 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](/deploy/web-call#handle-call-events),
[transcript authentication](/deploy/web-call#enable-live-transcripts), and
[audio options](/deploy/web-call#control-audio-during-the-call).

## 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`](/api-references/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](/api-references/get-call) if your application needs call fields
such as `call_status`, `agent_id`, or `metadata` after creation.