Create web call

Create a browser call and get the access token your front end uses to join it.

POSThttps://api.tried.com.au/v3/create-web-call

Creates a web call for an agent and returns a LiveKit access token. Pass access_token and livekit_url to the web SDK startCall() in the browser. The call stays registered until the browser joins.

Call this from your server with an API key. From a browser, you can call it with a public key (Authorization: Bearer public_key_...) from an allowed domain: the key's own voice agent is used and agent_id must match it or be omitted.

Request#

Body#

Field	Type	Required	Description
`agent_id`	string	Yes	Agent to talk to. Optional with a public key, which supplies its own agent.
`agent_version`	integer or string	No	Version to run. A number, or `latest`, `latest_published` or an environment tag name. Default: the latest version.
`retell_llm_dynamic_variables`	object	No	Values for `{{variables}}`. Non-string values are stored as JSON strings. Default `{}`.
`metadata`	object	No	Any JSON stored on the call. Default `{}`. With a public key, `public_key_id` and `origin` are added.

Example request#

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_3f9a1c0b2d4e5f6a7b8c9d0e",
  "retell_llm_dynamic_variables": {
    "customer_name": "Sam"
  },
  "metadata": {
    "page": "/pricing"
  }
}'

const res = await fetch("https://api.tried.com.au/v3/create-web-call", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRIED_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "agent_id": "agent_3f9a1c0b2d4e5f6a7b8c9d0e",
    "retell_llm_dynamic_variables": {
      "customer_name": "Sam"
    },
    "metadata": {
      "page": "/pricing"
    }
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://api.tried.com.au/v3/create-web-call",
    headers={"Authorization": f"Bearer {os.environ['TRIED_API_KEY']}"},
    json={
        "agent_id": "agent_3f9a1c0b2d4e5f6a7b8c9d0e",
        "retell_llm_dynamic_variables": {
            "customer_name": "Sam",
        },
        "metadata": {
            "page": "/pricing",
        },
    },
)
data = res.json()

Response#

201 Created with the call object plus the join details.

{
  "call_id": "call_2b3c4d5e6f7a8b9c0d1e2f3a",
  "call_type": "web_call",
  "agent_id": "agent_3f9a1c0b2d4e5f6a7b8c9d0e",
  "agent_version": 4,
  "agent_name": "Website concierge",
  "call_status": "registered",
  "direction": null,
  "from_number": null,
  "to_number": null,
  "metadata": { "page": "/pricing" },
  "retell_llm_dynamic_variables": { "customer_name": "Sam" },
  "collected_dynamic_variables": {},
  "start_timestamp": null,
  "end_timestamp": null,
  "duration_ms": null,
  "transcript": "",
  "transcript_object": [],
  "transcript_with_tool_calls": [],
  "recording_url": null,
  "recording_multi_channel_url": null,
  "public_log_url": null,
  "knowledge_base_retrieved_contents_url": null,
  "transfer_destination": null,
  "llm_token_usage": null,
  "disconnection_reason": null,
  "call_analysis": null,
  "latency": {},
  "call_cost": null,
  "batch_call_id": null,
  "contact_id": null,
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "livekit_url": "wss://livekit.tried.com.au",
  "expires_at": 1792396800000,
  "transport": "livekit",
  "ice_servers": [{ "urls": ["stun:stun.l.google.com:19302"] }]
}

Field	Type	Description
`access_token`	string	LiveKit JWT that lets the browser join the call's room.
`livekit_url`	string	LiveKit server URL to connect to.
`expires_at`	integer	Token expiry, epoch ms.
`transport`	string	Always `livekit`.
`ice_servers`	array	ICE servers for clients that need them. Defaults to Google's public STUN server; the server's `WEB_CALL_ICE_SERVERS` setting overrides it. LiveKit negotiates its own TURN.

Errors#

Status	When
`400`	Validation failed, or a version reference is unknown.
`401`	Missing or invalid API key.
`402`	Credit exhausted, budget reached or invoice overdue (`error_code` in the body).
`403`	The key's IP allowlist or scopes reject the request. This route needs the `calls` scope. With a public key: the Origin is not allowed, the key has no voice agent, `agent_id` differs from the key's agent, or reCAPTCHA failed.
`404`	The agent or version does not exist.
`429`	Rate limit exceeded. See Rate limits. The workspace concurrency limit is reached.

See Errors for the body format.

Compatibility notes#

Tried serves both /v3/create-web-call and /v2/create-web-call. Version references, the spend check, pre-call workflows and public key access apply to the /v3 path only. The token joins a LiveKit room, so use the Tried web SDK (it also exports the class as RetellWebClient).