Skip to main content
POST
JavaScript

Authorizations

Authorization
string
header
required

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Body

application/json
agent_id
string
required

Unique id of agent used for the call. Your agent would contain the LLM Websocket url used for this call.

Minimum string length: 1
Example:

"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD"

agent_version

The version of the agent to use for the call.

Required string length: 1 - 20
Pattern: ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$
Example:

"latest_published"

agent_override
object

For this particular call, override agent configuration with these settings. This allows you to customize agent behavior for individual calls without modifying the base agent.

metadata
object

An arbitrary object for storage purpose only. You can put anything here like your internal customer id associated with the call. Not used for processing. You can later get this field from the call object.

retell_llm_dynamic_variables
object

Add optional dynamic variables in key value pairs of string that injects into your Response Engine prompt and tool description. Only applicable for Response Engine.

Example:
current_node_id
string | null

Start the call at this conversation flow node (stage). Must be a valid node id in the agent's conversation flow. Only applicable when the agent uses conversation flow as the response engine. Ignored for retell-llm agents.

Example:

"collect_info"

current_state
string | null

Start the conversation in this state (stage). Must be a valid state name in the agent's Retell LLM. Only applicable when the agent uses Retell LLM with states. Ignored for conversation-flow agents.

Example:

"information_collection"

Response

Successfully created a web call.

call_id
string
required

Unique identifier for the web call.

Example:

"call_Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6"

access_token
string
required

Token authorizing this browser to join the web call. Pass it to your frontend.

Example:

"eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tSm9p"

transport
enum<string>
required

Connection transport to select in the web client.

Available options:
gateway
ice_servers
object[]
required

ICE servers to configure before the browser creates its peer connection.

expires_at
integer<int64>
required

Unix epoch ms when the access_token expires.

Example:

1735689600000