POST
/
v2
/
create-web-call
curl --request POST \
  --url https://api.retellai.com/v2/create-web-call \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json'
{
  "call_type": "web_call",
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tSm9p",
  "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "call_status": "registered",
  "metadata": {},
  "retell_llm_dynamic_variables": {
    "customer_name": "John Doe"
  },
  "opt_out_sensitive_data_storage": true,
  "start_timestamp": 1703302407333,
  "end_timestamp": 1703302428855,
  "transcript": "Agent: hi how are you doing?\nUser: Doing pretty well. How are you?\nAgent: That's great to hear! I'm doing well too, thanks! What's up?\nUser: I don't have anything in particular.\nAgent: Got it, just checking in!\nUser: Alright. See you.\nAgent: have a nice day\n ",
  "transcript_object": [
    {
      "role": "agent",
      "content": "hi how are you doing?",
      "words": [
        {
          "word": "hi",
          "start": 0.7,
          "end": 1.3
        }
      ]
    }
  ],
  "transcript_with_tool_calls": [
    {
      "role": "agent",
      "content": "hi how are you doing?",
      "words": [
        {
          "word": "hi",
          "start": 0.7,
          "end": 1.3
        }
      ]
    }
  ],
  "recording_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav",
  "public_log_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/public_log.txt",
  "e2e_latency": {
    "p50": 800,
    "p90": 1200,
    "p95": 1500,
    "p99": 2500,
    "max": 2700,
    "min": 500,
    "num": 10
  },
  "llm_latency": {
    "p50": 800,
    "p90": 1200,
    "p95": 1500,
    "p99": 2500,
    "max": 2700,
    "min": 500,
    "num": 10
  },
  "llm_websocket_network_rtt_latency": {
    "p50": 800,
    "p90": 1200,
    "p95": 1500,
    "p99": 2500,
    "max": 2700,
    "min": 500,
    "num": 10
  },
  "disconnection_reason": "agent_hangup",
  "call_analysis": {
    "call_summary": "The agent called the user to ask question about his purchase inquiry. The agent asked several questions regarding his preference and asked if user would like to book an appointment. The user happily agreed and scheduled an appointment next Monday 10am.",
    "user_sentiment": "Positive",
    "agent_sentiment": "Friendly",
    "agent_task_completion_rating": "Complete",
    "agent_task_completion_rating_reason": "User answered all of the question asked by the AI agent. User has an appointment set next Monday at 10am",
    "call_completion_rating": "Complete",
    "call_completion_rating_reason": "call was ended by the user. User said goodbye and hung up."
  }
}

Authorizations

Authorization
string
headerrequired

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.

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 Retell LLM prompt and tool description. Only applicable for Retell LLM.

Response

201 - application/json
call_type
enum<string>
required

Type of the call. Used to distinguish between web call and phone call.

Available options:
web_call
access_token
string
required

Access token to enter the web call room. This needs to be passed to your frontend to join the call.

call_id
string
required

Unique id of the call. Used to identify in LLM websocket and used to authenticate in audio websocket.

agent_id
string
required

Corresponding agent id of this call.

call_status
enum<string>
required

Status of call.

  • registered: Call id issued, starting to make a call using this id.

  • ongoing: Call connected and ongoing.

  • ended: The underlying websocket has ended for the call. Either user or agent hanged up, or call transferred.

  • error: Call encountered error.

Available options:
registered,
ongoing,
ended,
error
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 Retell LLM prompt and tool description. Only applicable for Retell LLM.

opt_out_sensitive_data_storage
boolean

Whether this call opts out of sensitive data storage like transcript, recording, logging.

start_timestamp
integer

Begin timestamp (milliseconds since epoch) of the call. Available after call starts.

end_timestamp
integer

End timestamp (milliseconds since epoch) of the call. Available after call ends.

transcript
string

Transcription of the call. Available after call ends.

transcript_object
object[]

Transcript of the call in the format of a list of utterance, with timestamp. Available after call ends.

transcript_with_tool_calls
object[]

Transcript of the call weaved with tool call invocation and results. It precisely captures when (at what utterance, which word) the tool was invoked and what was the result. Available after call ends.

recording_url
string

Recording of the call. Available after call ends.

public_log_url
string

Public log of the call, containing details about all the requests and responses received in LLM WebSocket, latency tracking for each turntaking, helpful for debugging and tracing. Available after call ends.

e2e_latency
object

End to end latency (from user stops talking to agent start talking) tracking of the call, available after call ends. This latency does not account for the network trip time from Retell server to user frontend. The latency is tracked every time turn change between user and agent.

llm_latency
object

LLM latency (from issue of LLM call to first token received) tracking of the call, available after call ends. When using custom LLM. this latency includes LLM websocket roundtrip time between user server and Retell server.

llm_websocket_network_rtt_latency
object

LLM websocket roundtrip latency (between user server and Retell server) tracking of the call, available after call ends. Only populated for calls using custom LLM.

disconnection_reason
enum<string>

The reason for the disconnection of the call. Read details desciption about reasons listed here at Disconnection Reason Doc.

Available options:
user_hangup,
agent_hangup,
call_transfer,
inactivity,
machine_detected,
concurrency_limit_reached,
dial_busy,
dial_failed,
dial_no_answer,
error_llm_websocket_open,
error_llm_websocket_lost_connection,
error_llm_websocket_runtime,
error_llm_websocket_corrupt_payload,
error_frontend_corrupted_payload,
error_twilio,
error_no_audio_received,
error_asr,
error_retell,
error_unknown
call_analysis
object
  • BETA feature, schema might change, might not always be populated. Please do not rely on this object schema for post processing. Post conversation evaluation of the call. Including information such as sentiment, intent, call completion status and other metrics. Available after call ends. Subscribe to call_analyzed webhook event type to receive it once ready.

Was this page helpful?

Create Phone CallGet Call