Sign in

v28

latestOpenAPI 3.0.3Apache 2.0raw.githubusercontent.com2026-05-2887246443.7 KB

Create a new web call

post/v2/create-web-call

Request body

agent_idstring required

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

metadataobject

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_variablesobject

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.

current_node_idstring nullable

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.

current_statestring nullable

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 request

{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "agent_version": 1,
  "agent_override": {
    "agent": {
      "agent_name": "Jarvis",
      "version_description": "Customer support agent for handling product inquiries",
      "voice_id": "retell-Cimo",
      "fallback_voice_ids": [
        "cartesia-Cimo",
        "minimax-Cimo"
      ],
      "voice_temperature": 1,
      "voice_speed": 1,
      "enable_dynamic_voice_speed": true,
      "enable_dynamic_responsiveness": true,
      "volume": 1,
      "voice_emotion": "calm",
      "responsiveness": 1,
      "interruption_sensitivity": 1,
      "enable_backchannel": true,
      "backchannel_frequency": 0.9,
      "backchannel_words": [
        "yeah",
        "uh-huh"
      ],
      "reminder_trigger_ms": 10000,
      "reminder_max_count": 2,
      "ambient_sound_volume": 1,
      "language": "en-US",
      "webhook_url": "https://webhook-url-here",
      "webhook_timeout_ms": 10000,
      "boosted_keywords": [
        "retell",
        "kroger"
      ],
      "data_storage_setting": "everything",
      "data_storage_retention_days": 30,
      "opt_in_signed_url": true,
      "signed_url_expiration_ms": 86400000,
      "pronunciation_dictionary": [
        {
          "word": "actually",
          "alphabet": "ipa",
          "phoneme": "ˈæktʃuəli"
        }
      ],
      "end_call_after_silence_ms": 600000,
      "max_call_duration_ms": 3600000,
      "voicemail_message": "Hi, please give us a callback.",
      "voicemail_detection_timeout_ms": 30000,
      "voicemail_option": {
        "action": {
          "type": "static_text",
          "text": "Please give us a callback tomorrow at 10am."
        }
      },
      "ivr_option": {
        "action": {
          "type": "hangup"
        }
      },
      "call_screening_option": {
        "agent_identity": "Acme Health scheduling team",
        "call_purpose": "confirming your appointment for tomorrow"
      },
      "post_call_analysis_data": [
        {
          "type": "string",
          "name": "customer_name",
          "description": "The name of the customer.",
          "examples": [
            "John Doe",
            "Jane Smith"
          ]
        }
      ],
      "analysis_successful_prompt": "The agent finished the task and the call was complete without being cutoff.",
      "analysis_summary_prompt": "Summarize the outcome of the conversation in two sentences.",
      "analysis_user_sentiment_prompt": "Evaluate the user's sentiment based on their tone and satisfaction level.",
      "begin_message_delay_ms": 1000,
      "ring_duration_ms": 30000,
      "stt_mode": "fast",
      "vocab_specialization": "general",
      "allow_user_dtmf": true,
      "user_dtmf_options": {
        "termination_key": "#"
      },
      "denoising_mode": "noise-cancellation",
      "timezone": "America/New_York"
    },
    "retell_llm": {
      "s2s_model": "gpt-realtime-1.5",
      "model_high_priority": true,
      "tool_call_strict_mode": true,
      "kb_config": {
        "top_k": 3,
        "filter_score": 0.6
      },
      "begin_after_user_silence_ms": 2000,
      "begin_message": "Hey I am a virtual assistant calling from Retell Hospital."
    },
    "conversation_flow": {
      "model_temperature": 0.7,
      "tool_call_strict_mode": true,
      "knowledge_base_ids": [
        "kb_001",
        "kb_002"
      ],
      "kb_config": {
        "top_k": 3,
        "filter_score": 0.6
      },
      "start_speaker": "agent",
      "begin_after_user_silence_ms": 2000
    }
  },
  "retell_llm_dynamic_variables": {
    "customer_name": "John Doe"
  },
  "current_node_id": "collect_info",
  "current_state": "information_collection"
}

Response

Successfully created a web call.

call_type'web_call' required

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

access_tokenstring required

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

call_idstring required

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

agent_idstring required

Corresponding agent id of this call.

agent_namestring

Name of the agent.

agent_versioninteger required

The version of the agent.

call_status'registered' | 'not_connected' | 'ongoing' | 'ended' | 'error' 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 hung up, or call transferred.
  • error: Call encountered error.
metadataobject

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_variablesobject

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.

collected_dynamic_variablesobject

Dynamic variables collected from the call. Only available after the call ends.

custom_sip_headersobject

Custom SIP headers to be added to the call.

data_storage_setting'everything' | 'everything_except_pii' | 'basic_attributes_only' nullable

Data storage setting for this call's agent. "everything" stores all data, "everything_except_pii" excludes PII when possible, "basic_attributes_only" stores only metadata.

opt_in_signed_urlboolean

Whether this agent opts in for signed URLs for public logs and recordings. When enabled, the generated URLs will include security signatures that restrict access and automatically expire after 24 hours.

start_timestampinteger

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

end_timestampinteger

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

transfer_end_timestampinteger

Transfer end timestamp (milliseconds since epoch) of the call. Available after transfer call ends.

duration_msinteger

Duration of the call in milliseconds. Available after call ends.

transcriptstring

Transcription of the call. Available after call ends.

recording_urlstring

Recording of the call. Available after call ends.

recording_multi_channel_urlstring

Recording of the call, with each party's audio stored in a separate channel. Available after the call ends.

scrubbed_recording_urlstring

Recording of the call without PII. Available after call ends.

scrubbed_recording_multi_channel_urlstring

Recording of the call without PII, with each party's audio stored in a separate channel. Available after the call ends.

public_log_urlstring

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.

knowledge_base_retrieved_contents_urlstring

URL to the knowledge base retrieved contents of the call. Available after call ends if the call utilizes knowledge base feature. It consists of the respond id and the retrieved contents related to that response. It's already rendered in call history tab of dashboard, and you can also manually download and check against the transcript to view the knowledge base retrieval results.

disconnection_reason'user_hangup' | 'agent_hangup' | 'call_transfer' | 'voicemail_reached' | 'ivr_reached' | 'inactivity' | 'max_duration_reached' | 'concurrency_limit_reached' | 'no_concurrency_fallback' | 'no_valid_payment' | 'scam_detected' | 'dial_busy' | 'dial_failed' | 'dial_no_answer' | 'invalid_destination' | 'telephony_provider_permission_denied' | 'telephony_provider_unavailable' | 'sip_routing_error' | 'marked_as_spam' | 'user_declined' | 'error_llm_websocket_open' | 'error_llm_websocket_lost_connection' | 'error_llm_websocket_runtime' | 'error_llm_websocket_corrupt_payload' | 'error_no_audio_received' | 'error_asr' | 'error_retell' | 'error_unknown' | 'error_user_not_joined' | 'registered_call_timeout' | 'transfer_bridged' | 'transfer_cancelled' | 'manual_stopped'
transfer_destinationstring nullable

The destination number or identifier where the call was transferred to. Only populated when the disconnection reason was call_transfer. Can be a phone number or a SIP URI. SIP URIs are prefixed with "sip:" and may include a ";transport=..." portion (if transport is known) where the transport type can be "tls", "tcp" or "udp".

Example response

{
  "call_type": "web_call",
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tSm9p",
  "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "agent_name": "My Agent",
  "agent_version": 1,
  "call_status": "registered",
  "retell_llm_dynamic_variables": {
    "customer_name": "John Doe"
  },
  "collected_dynamic_variables": {
    "last_node_name": "Test node"
  },
  "custom_sip_headers": {
    "X-Custom-Header": "Custom Value"
  },
  "data_storage_setting": "everything",
  "opt_in_signed_url": true,
  "start_timestamp": 1703302407333,
  "end_timestamp": 1703302428855,
  "transfer_end_timestamp": 1703302628855,
  "duration_ms": 10000,
  "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
        }
      ]
    }
  ],
  "scrubbed_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",
  "recording_multi_channel_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav",
  "scrubbed_recording_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav",
  "scrubbed_recording_multi_channel_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav",
  "public_log_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/public_log.txt",
  "knowledge_base_retrieved_contents_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/kb_retrieved_contents.txt",
  "latency": {
    "e2e": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10
    },
    "asr": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10
    },
    "llm": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10
    },
    "llm_websocket_network_rtt": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10
    },
    "tts": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10
    },
    "knowledge_base": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10
    },
    "s2s": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10
    }
  },
  "transfer_destination": "+12137771234",
  "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",
    "call_successful": true
  },
  "call_cost": {
    "product_costs": [
      {
        "product": "elevenlabs_tts",
        "unit_price": 1,
        "cost": 60
      }
    ],
    "total_duration_seconds": 60,
    "total_duration_unit_price": 1,
    "combined_cost": 70
  }
}