Web calls

A web call connects a browser microphone to an agent over WebRTC, with no phone number. Your backend creates the call and gets an access_token; your page joins the call with the web SDK. Web calls use the same agent, prompt, tools and post-call analysis as phone calls, and count against the same concurrency limit.

There are three ways to start one:

• Your own page, with POST /v3/create-web-call from your server and @tried/web-sdk in the browser.
• A public key, so the browser can call POST /v3/create-web-call itself from an allowed domain. See Chat widget.
• A Voice Orb share link, a hosted page anyone with the link can use.

Create the call on your server#

curl -X POST https://api.tried.com.au/v3/create-web-call \
  -H "Authorization: Bearer $TRIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_8e0c...",
    "retell_llm_dynamic_variables": { "first_name": "Sam" },
    "metadata": { "session": "abc" }
  }'

POST /v2/create-web-call is an alias.

The response is HTTP 201 with the call object (call_type: "web_call", call_status: "registered", direction: null) plus:

Keep your API key on the server. Send only access_token and livekit_url to the browser.

Join from the browser#

@tried/web-sdk wraps livekit-client with the same API as Retell's retell-client-js-sdk. RetellWebClient is exported as an alias, so existing front ends switch by changing the import.

import { TriedWebClient } from "@tried/web-sdk";

const client = new TriedWebClient();

client.on("call_started", () => console.log("connected"));
client.on("agent_start_talking", () => setTalking(true));
client.on("agent_stop_talking", () => setTalking(false));
client.on("update", ({ transcript }) => render(transcript));
client.on("call_ended", () => console.log("ended"));
client.on("error", (err) => console.error(err));

const { access_token, livekit_url } = await fetch("/api/start-call", { method: "POST" }).then((r) => r.json());
await client.startCall({ accessToken: access_token, livekitUrl: livekit_url });

startCall options#

The microphone uses echo cancellation, noise suppression and auto gain control.

Methods#

Events#

The agent leaving the room ends the call on the client.

Voice Orb share links#

A Voice Orb link is a public page at /orb/<token> where anyone with the link can talk to an agent in their browser. Use it to share an agent with a colleague or a client before you build your own front end.

The page shows the agent name, the workspace name and an animated orb. With LiveKit configured, the visitor talks by voice: the page calls POST /public/share/<token>/web-call, which creates a normal web call with metadata.source: "voice_orb". Without LiveKit it falls back to text chat.

• Calls are billed to the workspace that owns the agent.
• When the workspace is out of credit or over its monthly budget, the page gets HTTP 402.
• API endpoints: GET /agents/:agent_id/share-links, POST /agents/:agent_id/share-links, DELETE /share-links/:id. Each link has share_link_id, token, enabled and url_path.

Test in the dashboard#

The agent builder's Test Audio panel runs a web call against the current draft. Call transfer does not work in web calls because there is no phone line to transfer.

Limits and gotchas#

• Web calls count against the workspace concurrency limit and cannot use reserved inbound slots. A full workspace returns 429.
• The access token expires after 1 hour. Create the call right before the user joins.
• Voicemail, IVR and call screening detection also runs for the first 3 minutes of web calls.

Related#

• Chat widget and public keys
• Concurrency
• Create web call API