Migrate Retell web calls from v2 to v3

Create Web Call v2 is deprecated

Deprecation date: 09/30/2026 POST /v2/create-web-call will be deprecated on September 30, 2026 in favor of POST /v3/create-web-call. Existing integrations continue working during migration. Upgrade your browser JavaScript SDK and update how your integration creates calls.

Upgrade the browser SDK

Upgrade to the latest browser SDK:

npm install retell-client-js-sdk@latest

Upgrading the package alone does not migrate code that still sends requests to /v2/create-web-call. The SDK’s RetellWebClient compatibility class continues to accept v2 tokens in 3.x.

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.

Migrate server-created calls

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.

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.

​Create Web Call v2 is deprecated

​Upgrade the browser SDK

​Replace call creation and connection

​Migrate server-created calls

​Update event handlers

Create Web Call v2 is deprecated

Upgrade the browser SDK

Replace call creation and connection

Migrate server-created calls

Update event handlers