Make a web call

Make browser voice calls with Retell AI: use the JavaScript SDK to connect users to an agent, control microphone audio, and handle transcripts and call events.

A web call connects a user to your voice agent directly in the browser, using their microphone and speakers. The Retell Web SDK creates the call and connects its audio; no phone number is involved.

When to use web calls

• Voice inside your product. Add a support agent to your help center, a sales assistant to a landing page, or voice-guided onboarding, with a UI you fully control.
• Custom call experiences. Build call controls and audio visualizations. Enable live transcripts separately for captions or conversation flow updates.
• Development and testing. Talk to an agent while building it. For a quick test without writing code, use the dashboard’s web call testing.

If you want a voice entry point on your website without building a frontend, embed the website widget. To reach users on their phones, see outbound calls and inbound calls.

For example, an e-commerce site adds a “Talk to support” button to its order page. Clicking it starts a web call that passes the customer’s name and order ID as dynamic variables, so the agent can look up the right order.

Set up web calls

1. Install the Web SDK

   npm install retell-client-js-sdk@latest
   
2. Configure authentication

   Create a public key and allow your website’s domain. Add localhost to test locally. Use the public key in your browser code; keep API keys on your server.

   If your public key has reCAPTCHA enabled, obtain a fresh token before each call and pass it as recaptchaToken to createWebCall().

3. Create and connect the call

   Initialize RetellClient and call createWebCall() from your button’s click handler. Replace the public key and agent ID with your own values.

   import { RetellClient } from "retell-client-js-sdk";
   
   const client = new RetellClient({ key: "public_key_YOUR_PUBLIC_KEY" });
   let call;
   
   function startCall() {
     if (call && call.status !== "ended") return;
   
     call = client.createWebCall({
       agent_id: "agent_oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
       retell_llm_dynamic_variables: { customer_name: "John Doe" },
       metadata: { internal_customer_id: "cust_123" },
       hooks: {
         onStatus: (status) => console.log("Call status:", status),
         onEnd: () => console.log("Call ended"),
         onError: (error) => console.error("Call error:", error),
       },
     });
   }
   

   createWebCall() returns a session immediately with status: "connecting", then reports live and ended through onStatus. Audio may take a moment to connect after live. Once creation succeeds, call.callId identifies the call.

   The browser prompts for microphone permission. Serve your page over HTTPS; localhost also works during development.

   agent_id is the only required call option. Common optional fields:

   Field	What it does
   retell_llm_dynamic_variables	String key-value pairs injected into the agent’s prompt and tool descriptions as dynamic variables.
   metadata	An arbitrary object stored on the call, such as an internal customer ID. Not used for processing; returned when you retrieve the call later.
   agent_version	The numeric agent version to use for this call.
   agent_override	Override agent configuration for this call only.

   See Create Web Call for the REST request fields, and audio controls for browser audio options.

4. End the call

   await call?.end();
   

   The agent can also end the call. Either way, the session reports ended through onStatus and fires onEnd.

Handle call events

Pass hooks when creating the call, as shown above, or register listeners on the returned session:

call.on("end", () => {
  console.log("Call ended");
});

Hook	Event	When it fires
onStatus	status	The session reports live or ended. Read the initial call.status for connecting.
onAudio	audio	An audio visualization snapshot is available. Requires audio.emitRawAudioSamples.
onEnd	end	The session ends, including after a failed connection. The payload may be empty.
onError	error	The SDK reports an error, such as a failed creation request or microphone permission denial. The payload is an Error object.
onTranscript	transcript	The live transcript changes. Requires the transcript connection described below.
onNodeTransition	node_transition	A conversation flow node first appears in the transcript, including nodes in the initial snapshot. Requires the transcript connection.

Reset call controls in onEnd, including when no onError fires. Use Get Call for the recorded disconnection reason.

Enable live transcripts

Live transcripts use a separate monitoring WebSocket and are off by default. With the public-key client configured above, add transcript: true:

call = client.createWebCall({
  agent_id: "agent_oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  transcript: true,
  hooks: {
    onTranscript: (transcript, preSessionTranscript) => {
      console.log("Conversation:", transcript);
      console.log("Pre-session tools:", preSessionTranscript);
    },
    onNodeTransition: (transition) => console.log("Flow node:", transition),
    onError: (error) => console.error("Call error:", error),
  },
});

onTranscript receives the full transcript so far and a separate array of pre-session tool calls. The SDK merges updates by each item’s stable ID. Items include spoken turns, tool calls, and flow nodes; see the transcript item spec. Transcript text can change as a turn progresses and does not mark exact speaking boundaries.

If the optional transcript connection fails, the SDK logs a console warning and the audio call continues. This failure does not fire onError. See WebSocket authentication if you create calls through your own backend.

To follow a web call from a second screen, or to let a supervisor step in, see Monitor live calls.

Control audio during the call

Mute and unmute the microphone without ending the call:

call.mute();
call.unmute();

Some browsers block playback until the user interacts with the page. To resume audio, call this from a click handler:

await call.startAudioPlayback();

Pass capture, playback, or visualization settings in the audio option of createWebCall():

Option	Type	Description
sampleRate	number	Requested audio sample rate. See audio basics.
captureDeviceId	string	Microphone device ID.
playbackDeviceId	string	Speaker device ID.
emitRawAudioSamples	boolean	Emit Float32Array snapshots through onAudio or the audio event. Defaults to false.

Use onAudio snapshots to calculate a level for an orb or volume meter. They contain incoming audio, including any background sound, and are sampled for visualization rather than continuous recording.

After the call

Collect full results after the call ends:

• Register a webhook to receive call_started, call_ended, and call_analyzed events on your server.
• Use call.callId with the get call API to fetch the complete transcript, recording, and analysis, or review the call in session history.

Example project

The React and Node.js demo uses RetellClient with an API key kept on the Node.js backend.

FAQ

Why does my call fail before it starts?

Read the error passed to onError. Check your public key’s allowed domains, the agent ID, and microphone permission. If reCAPTCHA is enabled, provide a fresh token for each call.

Why can't the user hear the agent?

Browsers can block audio playback before user interaction. Start the call from a click handler, or call call.startAudioPlayback() inside one.

Why doesn't the microphone work?

The user may have denied microphone permission, or the page isn’t served over HTTPS. Microphone access requires a secure context; localhost works during development.

How do I pass customer data into the call?

Use retell_llm_dynamic_variables for values the agent should use in conversation. Use metadata for values you only need to look up later, such as an internal customer ID. See dynamic variables.

Do web calls count toward my concurrency limit?

Yes. Web calls draw from the same concurrency pool as outbound phone calls.