--- title: "POST /v2/create-web-call" method: POST path: "/v2/create-web-call" --- # POST /v2/create-web-call `POST /v2/create-web-call` Create a new web call ## Request body - object - `agent_id` string, required — Unique id of agent used for the call. Your agent would contain the LLM Websocket url used for this call. - `agent_version` union — Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any. - integer - string - `agent_override` AgentOverrideRequest — Override configuration for agent, retell LLM, or conversation flow settings for a specific call. - `agent` AgentRequest - `response_engine` union - ResponseEngineRetellLm - `type` 'retell-llm', required — type of the Response Engine. - `llm_id` string, required — id of the Retell LLM Response Engine. - `version` number, nullable — Version of the Retell LLM Response Engine. - ResponseEngineCustomLm - `type` 'custom-llm', required — type of the Response Engine. - `llm_websocket_url` string, required — LLM websocket url of the custom LLM. - ResponseEngineConversationFlow - `type` 'conversation-flow', required — type of the Response Engine. - `conversation_flow_id` string, required — ID of the Conversation Flow Response Engine. - `version` number, nullable — Version of the Conversation Flow Response Engine. - `agent_name` string, nullable — The name of the agent. Only used for your own reference. - `version_description` string, nullable — Optional description of the agent version. Used for your own reference and documentation. - `voice_id` string — Unique voice id used for the agent. Find list of available voices and their preview in Dashboard. - `voice_model` 'eleven_turbo_v2' | 'eleven_flash_v2' | 'eleven_turbo_v2_5' | 'eleven_flash_v2_5' | 'eleven_multilingual_v2' | 'eleven_v3' | 'sonic-3' | 'sonic-3-latest' | 'sonic-3.5' | 'tts-1' | 'gpt-4o-mini-tts' | 'speech-02-turbo' | 'speech-2.8-turbo' | 's1' | 's2-pro' | 's2.1-pro' | 'null', nullable — Select the voice model used for the selected voice. Each provider has a set of available voice models. Set to null to remove voice model selection, and default ones will apply. Check out dashboard for more details of each voice model. - `fallback_voice_ids` string[], nullable — When TTS provider for the selected voice is experiencing outages, we would use fallback voices listed here for the agent. Voice id and the fallback voice ids must be from different TTS providers. The system would go through the list in order, if the first one in the list is also having outage, it would use the next one. Set to null to remove voice fallback for the agent. - `voice_temperature` number — Controls how stable the voice is. Value ranging from [0,2]. Lower value means more stable, and higher value means more variant speech generation. Check the dashboard to see what provider supports this feature. If unset, default value 1 will apply. - `voice_speed` number — Controls speed of voice. Value ranging from [0.5,2]. Lower value means slower speech, while higher value means faster speech rate. If unset, default value 1 will apply. - `enable_dynamic_voice_speed` boolean — If set to true, will enable dynamic voice speed adjustment based on the user's speech rate and conversation context. If unset, default value false will apply. - `enable_dynamic_responsiveness` boolean — If set to true, the agent will dynamically adjust how quickly it responds based on the user's speech rate and past turn-taking behavior in the call. If unset, default value false will apply. - `volume` number — If set, will control the volume of the agent. Value ranging from [0,2]. Lower value means quieter agent speech, while higher value means louder agent speech. If unset, default value 1 will apply. - `voice_emotion` 'calm' | 'sympathetic' | 'happy' | 'sad' | 'angry' | 'fearful' | 'surprised' | 'null', nullable — Controls the emotional tone of the agent's voice. Currently supported for Cartesia and Minimax TTS providers. If unset, no emotion will be used. - `responsiveness` number — Controls how responsive is the agent. Value ranging from [0,1]. Lower value means less responsive agent (wait more, respond slower), while higher value means faster exchanges (respond when it can). If unset, default value 1 will apply. - `interruption_sensitivity` number — Controls how sensitive the agent is to user interruptions. Value ranging from [0,1]. Lower value means it will take longer / more words for user to interrupt agent, while higher value means it's easier for user to interrupt agent. If unset, default value 1 will apply. When this is set to 0, agent would never be interrupted. - `enable_backchannel` boolean — Controls whether the agent would backchannel (agent interjects the speaker with phrases like "yeah", "uh-huh" to signify interest and engagement). Backchannel when enabled tends to show up more in longer user utterances. If not set, agent will not backchannel. - `backchannel_frequency` number — Only applicable when enable_backchannel is true. Controls how often the agent would backchannel when a backchannel is possible. Value ranging from [0,1]. Lower value means less frequent backchannel, while higher value means more frequent backchannel. If unset, default value 0.8 will apply. - `backchannel_words` string[], nullable — Only applicable when enable_backchannel is true. A list of words that the agent would use as backchannel. If not set, default backchannel words will apply. Check out [backchannel default words](/agent/interaction-configuration#backchannel) for more details. Note that certain voices do not work too well with certain words, so it's recommended to experiment before adding any words. - `reminder_trigger_ms` number — If set (in milliseconds), will trigger a reminder to the agent to speak if the user has been silent for the specified duration after some agent speech. Must be a positive number. If unset, default value of 10000 ms (10 s) will apply. - `reminder_max_count` integer — If set, controls how many times agent would remind user when user is unresponsive. Must be a non negative integer. If unset, default value of 1 will apply (remind once). Set to 0 to disable agent from reminding. - `ambient_sound` 'coffee-shop' | 'convention-hall' | 'summer-outdoor' | 'mountain-outdoor' | 'static-noise' | 'call-center' | 'null', nullable — If set, will add ambient environment sound to the call to make experience more realistic. Currently supports the following options: - `coffee-shop`: Coffee shop ambience with people chatting in background. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/coffee-shop.wav) - `convention-hall`: Convention hall ambience, with some echo and people chatting in background. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/convention-hall.wav) - `summer-outdoor`: Summer outdoor ambience with cicada chirping. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/summer-outdoor.wav) - `mountain-outdoor`: Mountain outdoor ambience with birds singing. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/mountain-outdoor.wav) - `static-noise`: Constant static noise. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/static-noise.wav) - `call-center`: Call center work noise. [Listen to Ambience](https://retell-utils-public.s3.us-west-2.amazonaws.com/call-center.wav) Set to `null` to remove ambient sound from this agent. - `ambient_sound_volume` number — If set, will control the volume of the ambient sound. Value ranging from [0,2]. Lower value means quieter ambient sound, while higher value means louder ambient sound. If unset, default value 1 will apply. - `language` union — Specifies what language(s) the agent will operate in. Accepts either a single scalar locale (e.g. `en-US`), the legacy scalar value `multi` for multilingual support, or an array of concrete locale codes for explicit multi-locale selection (e.g. `["en-US","es-ES"]`). The array form must contain concrete locale codes only — the `multi` value is valid only as the scalar legacy form and must not appear inside an array. Single-element arrays are normalized to the equivalent scalar on output. If unset, defaults to `en-US`. - union — Legacy single-string language format. Accepts any concrete locale from `Language`, plus the special scalar value `multi` for multilingual support. If unset, will use default value `en-US`. - 'en-US' | 'en-IN' | 'en-GB' | 'en-AU' | 'en-NZ' | 'de-DE' | 'es-ES' | 'es-419' | 'hi-IN' | 'fr-FR' | 'fr-CA' | 'ja-JP' | 'pt-PT' | 'pt-BR' | 'zh-CN' | 'ru-RU' | 'it-IT' | 'ko-KR' | 'nl-NL' | 'nl-BE' | 'pl-PL' | 'tr-TR' | 'vi-VN' | 'ro-RO' | 'bg-BG' | 'ca-ES' | 'th-TH' | 'da-DK' | 'fi-FI' | 'el-GR' | 'hu-HU' | 'id-ID' | 'no-NO' | 'sk-SK' | 'sv-SE' | 'lt-LT' | 'lv-LV' | 'cs-CZ' | 'ms-MY' | 'af-ZA' | 'ar-SA' | 'az-AZ' | 'bs-BA' | 'cy-GB' | 'fa-IR' | 'fil-PH' | 'gl-ES' | 'he-IL' | 'hr-HR' | 'hy-AM' | 'is-IS' | 'kk-KZ' | 'kn-IN' | 'mk-MK' | 'mr-IN' | 'ne-NP' | 'sl-SI' | 'sr-RS' | 'sw-KE' | 'ta-IN' | 'ur-IN' | 'yue-CN' | 'uk-UA' — Specifies what language (and dialect) the agent will operate in. For instance, selecting `en-GB` optimizes speech recognition for British English and indexes knowledge bases with English. If unset, will use default value `en-US`. This enum does not include the legacy scalar value `multi`. - 'multi' - Language[] - `webhook_url` string, nullable — The webhook for agent to listen to call events. See what events it would get at [webhook doc](/features/webhook). If set, will binds webhook events for this agent to the specified url, and will ignore the account level webhook for this agent. Set to `null` to remove webhook url from this agent. - `webhook_events` string[], nullable — Which webhook events this agent should receive. If not set, defaults to call_started, call_ended, call_analyzed. - `webhook_timeout_ms` integer — The timeout for the webhook in milliseconds. If not set, default value of 10000 will apply. - `boosted_keywords` string[], nullable — Provide a customized list of keywords to bias the transcriber model, so that these words are more likely to get transcribed. Commonly used for names, brands, street, etc. Entries may reference dynamic variables with `{{variable}}` syntax. - `data_storage_setting` 'everything' | 'everything_except_pii' | 'basic_attributes_only' — Granular setting to manage how Retell stores sensitive data (transcripts, recordings, logs, etc.). This replaces the deprecated `opt_out_sensitive_data_storage` field. - `everything`: Store all data including transcripts, recordings, and logs. - `everything_except_pii`: Store data without PII when PII is detected. - `basic_attributes_only`: Store only basic attributes; no transcripts/recordings/logs. If not set, default value of "everything" will apply. - `data_storage_retention_days` integer, nullable — Number of days to retain call/chat data before automatic deletion. Must be between 1 and 730 days. If not set, data is retained forever (no automatic deletion). - `opt_in_signed_url` boolean — 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. - `signed_url_expiration_ms` integer, nullable — The expiration time for the signed url in milliseconds. Only applicable when opt_in_signed_url is true. If not set, default value of 86400000 (24 hours) will apply. - `pronunciation_dictionary` object[], nullable — A list of words / phrases and their pronunciation to be used to guide the audio synthesize for consistent pronunciation. Check the dashboard to see what provider supports this feature. Set to null to remove pronunciation dictionary from this agent. - `word` string, required — The string of word / phrase to be annotated with pronunciation. - `alphabet` 'ipa' | 'cmu', required — The phonetic alphabet to be used for pronunciation. - `phoneme` string, required — Pronunciation of the word in the format of a IPA / CMU pronunciation. - `end_call_after_silence_ms` integer — If users stay silent for a period after agent speech, end the call. The minimum value allowed is 10,000 ms (10 s). By default, this is set to 600000 (10 min). - `max_call_duration_ms` integer — Maximum allowed length for the call, will force end the call if reached. The minimum value allowed is 60,000 ms (1 min), and maximum value allowed is 7,200,000 (2 hours). By default, this is set to 3,600,000 (1 hour). - `voicemail_message` string — The message to be played when the call enters a voicemail. Note that this feature is only available for phone calls. If you want to hangup after hitting voicemail, set this to empty string. - `voicemail_detection_timeout_ms` integer — Configures when to stop running voicemail detection, as it becomes unlikely to hit voicemail after a couple minutes, and keep running it will only have negative impact. The minimum value allowed is 5,000 ms (5 s), and maximum value allowed is 180,000 (3 minutes). By default, this is set to 30,000 (30 s). - `voicemail_option` object, nullable — If this option is set, the call will try to detect voicemail in the first 3 minutes of the call. Actions defined (hangup, or leave a message) will be applied when the voicemail is detected. Set this to null to disable voicemail detection. - `action` union, required - VoicemailActionPrompt - `type` 'prompt', required - `text` string, required — The prompt used to generate the text to be spoken when the call is detected to be in voicemail. - VoicemailActionStaticText - `type` 'static_text', required - `text` string, required — The text to be spoken when the call is detected to be in voicemail. - VoicemailActionHangup - `type` 'hangup', required - VoicemailActionBridgeTransfer - `type` 'bridge_transfer', required - `detection_prompt` string, nullable — Optionally describe what should be treated as voicemail. Leave as null to use the default definition. - `ivr_option` object, nullable — If this option is set, the call will try to detect IVR in the first 3 minutes of the call. Actions defined will be applied when the IVR is detected. Set this to null to disable IVR detection. - `action` IvrAction, required - `type` 'hangup', required - `detection_prompt` string, nullable — Optionally describe what should be treated as an IVR. Leave as null to use the default definition. - `call_screening_option` CallScreeningOption, nullable — If this option is set, the agent prompt will include call screen handling instructions for identity and call purpose questions. Set this to null to disable call screen prompt instructions. - `agent_identity` string, required — Identity the agent should provide when a call screen asks who is calling. Dynamic variables are supported. - `call_purpose` string, required — Purpose the agent should provide when a call screen asks why it is calling. Dynamic variables are supported. - `post_call_analysis_data` PostCallAnalysisData[], nullable — Post call analysis data to extract from the call. This data will augment the pre-defined variables extracted in the call analysis. This will be available after the call ends. - union — Post-call analysis item (custom data or voice preset). Use for voice agent post_call_analysis_data; validates only call presets (call_summary, call_successful, user_sentiment). - union - StringAnalysisData - … - EnumAnalysisData - … - BooleanAnalysisData - … - NumberAnalysisData - … - CallPresetAnalysisData — System preset for post-call analysis (voice agents). Use in post_call_analysis_data to override prompts or mark fields optional. - `type` 'system-presets', required — Identifies this item as a system preset. - `name` 'call_summary' | 'call_successful' | 'user_sentiment', required — Preset identifier for voice agent analysis. - `description` string — Prompt or description for this preset. - `required` boolean — If false, this field is optional in the analysis. If true or unset, the field is required. - `conditional_prompt` string — Optional instruction to help decide whether this field needs to be populated. If not set, the field is always included. - `post_call_analysis_model` 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-5' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5.5' | 'claude-4.5-sonnet' | 'claude-4.6-sonnet' | 'claude-4.5-haiku' | 'gemini-2.5-flash-lite' | 'gemini-3.0-flash' | 'gemini-3.1-flash-lite' | 'null', nullable — Available LLM models for agents. - `analysis_successful_prompt` string, nullable — Prompt to determine whether the post call or chat analysis should mark the interaction as successful. Set to null to use the default prompt. - `analysis_summary_prompt` string, nullable — Prompt to guide how the post call or chat analysis summary should be generated. When unset, the default system prompt is used. Set to null to use the default prompt. - `analysis_user_sentiment_prompt` string, nullable — Prompt to guide how the post call or chat analysis should evaluate user sentiment. When unset, the default system prompt is used. Set to null to use the default prompt. - `begin_message_delay_ms` integer — If set, will delay the first message by the specified amount of milliseconds, so that it gives user more time to prepare to take the call. Valid range is [0, 5000]. If not set or set to 0, agent will speak immediately. Only applicable when agent speaks first. - `ring_duration_ms` integer — If set, the phone ringing will last for the specified amount of milliseconds. This applies for both outbound call ringtime, and call transfer ringtime. Default to 30000 (30 s). Valid range is [5000, 300000]. - `stt_mode` 'fast' | 'accurate' | 'custom' — If set, determines whether speech to text should focus on latency or accuracy. Default to fast mode. When set to custom, custom_stt_config must be provided. - `custom_stt_config` object, nullable — Custom STT configuration. Only used when stt_mode is set to custom. - `provider` 'azure' | 'deepgram' | 'soniox', required — ASR provider name. - `endpointing_ms` integer, required — Endpointing timeout in milliseconds. Minimum is 100 for Azure, 10 for Deepgram, 500 for Soniox - `vocab_specialization` 'general' | 'medical' — If set, determines the vocabulary set to use for transcription. This setting only applies for English agents, for non English agent, this setting is a no-op. Default to general. - `allow_user_dtmf` boolean — If set to true, DTMF input will be accepted and processed. If false, any DTMF input will be ignored. Default to true. - `allow_dtmf_interruption` boolean — If set to true, DTMF input will interrupt the agent even when interruption_sensitivity is 0. Can be overridden per conversation or subagent node. Default to false. - `user_dtmf_options` object, nullable - `digit_limit` number, nullable — The maximum number of digits allowed in the user's DTMF (Dual-Tone Multi-Frequency) input per turn. Once this limit is reached, the input is considered complete and a response will be generated immediately. - `termination_key` string, nullable — A single key that signals the end of DTMF input. Acceptable values include any digit (0-9), the pound/hash symbol (#), or the asterisk (*). - `timeout_ms` integer — The time (in milliseconds) to wait for user DTMF input before timing out. The timer resets with each digit received. - `denoising_mode` 'no-denoise' | 'noise-cancellation' | 'noise-and-background-speech-cancellation' — If set, determines what denoising mode to use. Use "no-denoise" to bypass all audio denoising. Default to noise-cancellation. - `pii_config` PIIConfig - `mode` 'post_call', required — The processing mode for PII scrubbing. Currently only post-call is supported. - `categories` string[], required — List of PII categories to scrub from transcripts and recordings. PII redaction is only active when this list is non-empty; an empty array means no PII scrubbing is performed. - `guardrail_config` GuardrailConfig - `output_topics` string[], nullable — Selected prohibited agent topic categories to check. When agent messages contain these topics, they will be replaced with a placeholder message. - `input_topics` string[], nullable — Selected prohibited user topic categories to check. When user messages contain these topics, the agent will respond with a placeholder message instead of processing the request. - `handbook_config` VoiceHandbookConfig — Behavior presets for voice agents. All presets are available. - `default_personality` boolean — Professional call center rep baseline. - `natural_filler_words` boolean — Sprinkle natural speech fillers like "um", "you know" for a more human, conversational tone. - `high_empathy` boolean — Warm acknowledgment of caller concerns. - `echo_verification` boolean — Repeat back and confirm important details (voice only). - `nato_phonetic_alphabet` boolean — Spell using NATO phonetic alphabet style (voice only). - `speech_normalization` boolean — Convert numbers/dates/currency to spoken forms (voice only). - `smart_matching` boolean — Treat near-match similar words as same entity to reduce impact of transcription error (voice only). - `ai_disclosure` boolean — When asked, acknowledge being a virtual assistant. - `scope_boundaries` boolean — Stay within prompt/context scope, don't invent details. - `timezone` string, nullable — IANA timezone for the agent (e.g. America/New_York). Defaults to America/Los_Angeles if not set. - `retell_llm` RetellLlmOverride — Override properties for Retell LLM configuration in agent override requests. - `model` 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-5' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5.5' | 'claude-4.5-sonnet' | 'claude-4.6-sonnet' | 'claude-4.5-haiku' | 'gemini-2.5-flash-lite' | 'gemini-3.0-flash' | 'gemini-3.1-flash-lite' | 'null', nullable — Available LLM models for agents. - `s2s_model` 'gpt-realtime-2' | 'gpt-realtime-1.5' | 'gpt-realtime' | 'gpt-realtime-mini' | 'null', nullable — Select the underlying speech to speech model. Can only set this or model, not both. - `model_temperature` number — If set, will control the randomness of the response. Value ranging from [0,1]. Lower value means more deterministic, while higher value means more random. If unset, default value 0 will apply. Note that for tool calling, a lower value is recommended. - `model_high_priority` boolean, nullable — If set to true, will use high priority pool with more dedicated resource to ensure lower and more consistent latency, default to false. This feature usually comes with a higher cost. - `tool_call_strict_mode` boolean, nullable — Whether to use strict mode for tool calls. Only applicable when using certain supported models. - `knowledge_base_ids` string[], nullable — A list of knowledge base ids to use for this resource. - `kb_config` KBConfig - `top_k` integer — Max number of knowledge base chunks to retrieve - `filter_score` number — Similarity threshold for filtering search results - `start_speaker` 'user' | 'agent' — The speaker who starts the conversation. Required. Must be either 'user' or 'agent'. - `begin_after_user_silence_ms` integer, nullable — If set, the AI will begin the conversation after waiting for the user for the duration (in milliseconds) specified by this attribute. This only applies if the agent is configured to wait for the user to speak first. If not set, the agent will wait indefinitely for the user to speak. - `begin_message` string, nullable — First utterance said by the agent in the call. If not set, LLM will dynamically generate a message. If set to "", agent will wait for user to speak first. - `conversation_flow` ConversationFlowOverride — Override properties for conversation flow configuration in agent override requests. - `model_choice` ModelChoice - `type` 'cascading', required — Type of model choice - `model` 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-5' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5.5' | 'claude-4.5-sonnet' | 'claude-4.6-sonnet' | 'claude-4.5-haiku' | 'gemini-2.5-flash-lite' | 'gemini-3.0-flash' | 'gemini-3.1-flash-lite', required — Available LLM models for agents. - `high_priority` boolean — Whether to use high priority pool with more dedicated resource, default false - `model_temperature` number, nullable — Controls the randomness of the model's responses. Lower values make responses more deterministic. - `tool_call_strict_mode` boolean, nullable — Whether to use strict mode for tool calls. Only applicable when using certain supported models. - `knowledge_base_ids` string[], nullable — Knowledge base IDs for RAG (Retrieval-Augmented Generation). - `kb_config` KBConfig - `top_k` integer — Max number of knowledge base chunks to retrieve - `filter_score` number — Similarity threshold for filtering search results - `start_speaker` 'user' | 'agent' — Who starts the conversation - user or agent. - `begin_after_user_silence_ms` integer, nullable — If set, the AI will begin the conversation after waiting for the user for the duration (in milliseconds) specified by this attribute. This only applies if the agent is configured to wait for the user to speak first. If not set, the agent will wait indefinitely for the user to speak. - `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. - `current_node_id` string, 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_state` string, 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. ## Response `201` Successfully created a web call. - V2WebCallResponse - `call_type` 'web_call', required — Type of the call. Used to distinguish between web call and phone 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 the call in the LLM websocket and used to authenticate in the audio websocket. - `agent_id` string, required — Corresponding agent id of this call. - `agent_name` string — Name of the agent. - `agent_version` integer, 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. - `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. - `collected_dynamic_variables` object — Dynamic variables collected from the call. Only available after the call ends. - `custom_sip_headers` object — 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_url` boolean — 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_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. - `transfer_end_timestamp` integer — Transfer end timestamp (milliseconds since epoch) of the call. Available after transfer call ends. - `duration_ms` integer — Duration of the call in milliseconds. Available after call ends. - `transcript` string — Transcription of the call. Available after call ends. - `transcript_object` Utterance[] — Transcript of the call in the format of a list of utterance, with timestamp. Available after call ends. - `role` 'agent' | 'user' | 'transfer_target', required — Documents whether this utterance is spoken by agent or user. - `content` string, required — Transcript of the utterances. - `words` object[], required — Array of words in the utterance with the word timestamp. Useful for understanding what word was spoken at what time. Note that the word timestamp is not guaranteed to be accurate, it's more like an approximation. - `word` string — Word transcript (with punctuation if applicable). - `start` number — Start time of the word in the call in second. This is relative audio time, not wall time. - `end` number — End time of the word in the call in second. This is relative audio time, not wall time. - `transcript_with_tool_calls` UtteranceOrToolCall[] — 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. - union - Utterance - `role` 'agent' | 'user' | 'transfer_target', required — Documents whether this utterance is spoken by agent or user. - `content` string, required — Transcript of the utterances. - `words` object[], required — Array of words in the utterance with the word timestamp. Useful for understanding what word was spoken at what time. Note that the word timestamp is not guaranteed to be accurate, it's more like an approximation. - `word` string — Word transcript (with punctuation if applicable). - `start` number — Start time of the word in the call in second. This is relative audio time, not wall time. - `end` number — End time of the word in the call in second. This is relative audio time, not wall time. - ToolCallInvocationUtterance - `role` 'tool_call_invocation', required — This is a tool call invocation. - `tool_call_id` string, required — Tool call id, globally unique. - `name` string, required — Name of the function in this tool call. - `arguments` string, required — Arguments for this tool call, it's a stringified JSON object. - `thought_signature` string — Optional thought signature from Google Gemini thinking models. This is used internally to maintain reasoning chain in multi-turn function calling. - ToolCallResultUtterance - `role` 'tool_call_result', required — This is the result of a tool call. - `tool_call_id` string, required — Tool call id, globally unique. - `content` string, required — Result of the tool call, can be a string, a stringified json, etc. - `successful` boolean — Whether the tool call was successful. - NodeTransitionUtterance - `role` 'node_transition', required — This is result of a node transition - `former_node_id` string, required — Former node id - `former_node_name` string, required — Former node name - `new_node_id` string, required — New node id - `new_node_name` string, required — New node name - `transition_type` 'global' | 'global_go_back' | 'interrupt_go_back' | 'normal' — How this node was reached. "global" means a global node transition, "global_go_back" means returning from a global node, "interrupt_go_back" means going back due to user interruption, and "normal" means a regular edge transition. - DTMFUtterance - `role` 'dtmf', required — Digit pressed by the user from their phone keypad. - `digit` string, required — The digit pressed by the user. Will be a single digit string like "1", "2", "3", "*", "#" etc. - SmsUtterance - `role` 'sms', required — SMS message received from the user during the call (for example while the agent is leaving a voicemail). Not part of the spoken conversation. - `content` string, required — Text content of the SMS message. - `multimedia` SmsMultimediaItem[] — Multimedia attachments (MMS). Display only; not relayed into the spoken conversation. - `url` string, required — URL of the multimedia attachment. - `summary` string — Optional textual summary of the attachment. - `time_sec` number, required — Time the SMS was received, in seconds relative to the start of the call. - InjectedUtterance - `role` 'injected', required — External context injected into the conversation via the update-live-call API. Not spoken by either party. - `content` string, required — The injected context text. - `time_sec` number, required — Time the context was injected, in seconds relative to the start of the call. - `scrubbed_transcript_with_tool_calls` UtteranceOrToolCall[] — Transcript of the call weaved with tool call invocation and results, without PII. It precisely captures when (at what utterance, which word) the tool was invoked and what was the result. Available after call ends. - union - Utterance - `role` 'agent' | 'user' | 'transfer_target', required — Documents whether this utterance is spoken by agent or user. - `content` string, required — Transcript of the utterances. - `words` object[], required — Array of words in the utterance with the word timestamp. Useful for understanding what word was spoken at what time. Note that the word timestamp is not guaranteed to be accurate, it's more like an approximation. - `word` string — Word transcript (with punctuation if applicable). - `start` number — Start time of the word in the call in second. This is relative audio time, not wall time. - `end` number — End time of the word in the call in second. This is relative audio time, not wall time. - ToolCallInvocationUtterance - `role` 'tool_call_invocation', required — This is a tool call invocation. - `tool_call_id` string, required — Tool call id, globally unique. - `name` string, required — Name of the function in this tool call. - `arguments` string, required — Arguments for this tool call, it's a stringified JSON object. - `thought_signature` string — Optional thought signature from Google Gemini thinking models. This is used internally to maintain reasoning chain in multi-turn function calling. - ToolCallResultUtterance - `role` 'tool_call_result', required — This is the result of a tool call. - `tool_call_id` string, required — Tool call id, globally unique. - `content` string, required — Result of the tool call, can be a string, a stringified json, etc. - `successful` boolean — Whether the tool call was successful. - NodeTransitionUtterance - `role` 'node_transition', required — This is result of a node transition - `former_node_id` string, required — Former node id - `former_node_name` string, required — Former node name - `new_node_id` string, required — New node id - `new_node_name` string, required — New node name - `transition_type` 'global' | 'global_go_back' | 'interrupt_go_back' | 'normal' — How this node was reached. "global" means a global node transition, "global_go_back" means returning from a global node, "interrupt_go_back" means going back due to user interruption, and "normal" means a regular edge transition. - DTMFUtterance - `role` 'dtmf', required — Digit pressed by the user from their phone keypad. - `digit` string, required — The digit pressed by the user. Will be a single digit string like "1", "2", "3", "*", "#" etc. - SmsUtterance - `role` 'sms', required — SMS message received from the user during the call (for example while the agent is leaving a voicemail). Not part of the spoken conversation. - `content` string, required — Text content of the SMS message. - `multimedia` SmsMultimediaItem[] — Multimedia attachments (MMS). Display only; not relayed into the spoken conversation. - `url` string, required — URL of the multimedia attachment. - `summary` string — Optional textual summary of the attachment. - `time_sec` number, required — Time the SMS was received, in seconds relative to the start of the call. - InjectedUtterance - `role` 'injected', required — External context injected into the conversation via the update-live-call API. Not spoken by either party. - `content` string, required — The injected context text. - `time_sec` number, required — Time the context was injected, in seconds relative to the start of the call. - `recording_url` string — Recording of the call. Available after call ends. - `recording_multi_channel_url` string — Recording of the call, with each party's audio stored in a separate channel. Available after the call ends. - `scrubbed_recording_url` string — Recording of the call without PII. Available after call ends. - `scrubbed_recording_multi_channel_url` string — Recording of the call without PII, with each party's audio stored in a separate channel. Available after the 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. - `knowledge_base_retrieved_contents_url` string — 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. - `latency` object — Latency tracking of the call, available after call ends. Not all fields here will be available, as it depends on the type of call and feature used. - `e2e` CallLatency - `p50` number — 50 percentile of latency, measured in milliseconds. - `p90` number — 90 percentile of latency, measured in milliseconds. - `p95` number — 95 percentile of latency, measured in milliseconds. - `p99` number — 99 percentile of latency, measured in milliseconds. - `max` number — Maximum latency in the call, measured in milliseconds. - `min` number — Minimum latency in the call, measured in milliseconds. - `num` number — Number of data points (number of times latency is tracked). - `values` number[] — All the latency data points in the call, measured in milliseconds. - `asr` CallLatency - `p50` number — 50 percentile of latency, measured in milliseconds. - `p90` number — 90 percentile of latency, measured in milliseconds. - `p95` number — 95 percentile of latency, measured in milliseconds. - `p99` number — 99 percentile of latency, measured in milliseconds. - `max` number — Maximum latency in the call, measured in milliseconds. - `min` number — Minimum latency in the call, measured in milliseconds. - `num` number — Number of data points (number of times latency is tracked). - `values` number[] — All the latency data points in the call, measured in milliseconds. - `llm` CallLatency - `p50` number — 50 percentile of latency, measured in milliseconds. - `p90` number — 90 percentile of latency, measured in milliseconds. - `p95` number — 95 percentile of latency, measured in milliseconds. - `p99` number — 99 percentile of latency, measured in milliseconds. - `max` number — Maximum latency in the call, measured in milliseconds. - `min` number — Minimum latency in the call, measured in milliseconds. - `num` number — Number of data points (number of times latency is tracked). - `values` number[] — All the latency data points in the call, measured in milliseconds. - `llm_websocket_network_rtt` CallLatency - `p50` number — 50 percentile of latency, measured in milliseconds. - `p90` number — 90 percentile of latency, measured in milliseconds. - `p95` number — 95 percentile of latency, measured in milliseconds. - `p99` number — 99 percentile of latency, measured in milliseconds. - `max` number — Maximum latency in the call, measured in milliseconds. - `min` number — Minimum latency in the call, measured in milliseconds. - `num` number — Number of data points (number of times latency is tracked). - `values` number[] — All the latency data points in the call, measured in milliseconds. - `tts` CallLatency - `p50` number — 50 percentile of latency, measured in milliseconds. - `p90` number — 90 percentile of latency, measured in milliseconds. - `p95` number — 95 percentile of latency, measured in milliseconds. - `p99` number — 99 percentile of latency, measured in milliseconds. - `max` number — Maximum latency in the call, measured in milliseconds. - `min` number — Minimum latency in the call, measured in milliseconds. - `num` number — Number of data points (number of times latency is tracked). - `values` number[] — All the latency data points in the call, measured in milliseconds. - `knowledge_base` CallLatency - `p50` number — 50 percentile of latency, measured in milliseconds. - `p90` number — 90 percentile of latency, measured in milliseconds. - `p95` number — 95 percentile of latency, measured in milliseconds. - `p99` number — 99 percentile of latency, measured in milliseconds. - `max` number — Maximum latency in the call, measured in milliseconds. - `min` number — Minimum latency in the call, measured in milliseconds. - `num` number — Number of data points (number of times latency is tracked). - `values` number[] — All the latency data points in the call, measured in milliseconds. - `s2s` CallLatency - `p50` number — 50 percentile of latency, measured in milliseconds. - `p90` number — 90 percentile of latency, measured in milliseconds. - `p95` number — 95 percentile of latency, measured in milliseconds. - `p99` number — 99 percentile of latency, measured in milliseconds. - `max` number — Maximum latency in the call, measured in milliseconds. - `min` number — Minimum latency in the call, measured in milliseconds. - `num` number — Number of data points (number of times latency is tracked). - `values` number[] — All the latency data points in the call, measured in milliseconds. - `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_destination` string, 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". - `call_analysis` CallAnalysis - `call_summary` string — A high level summary of the call. - `in_voicemail` boolean — Whether the call is entered voicemail. - `user_sentiment` 'Negative' | 'Positive' | 'Neutral' | 'Unknown' — Sentiment of the user in the call. - `call_successful` boolean — Whether the agent seems to have a successful call with the user, where the agent finishes the task, and the call was complete without being cutoff. - `custom_analysis_data` object — Custom analysis data that was extracted based on the schema defined in agent post call analysis data. Can be empty if nothing is specified. - `call_cost` object — Cost of the call, including all the products and their costs and discount. - `product_costs` ProductCost[], required — List of products with their unit prices and costs in cents - `product` string, required — Product name that has a cost associated with it. - `unit_price` number — Unit price of the product in cents per second. - `cost` number, required — Cost for the product in cents for the duration of the call. - `is_transfer_leg_cost` boolean — True if this cost item is for a transfer segment. - `total_duration_seconds` number, required — Total duration of the call in seconds - `total_duration_unit_price` number, required — Total unit duration price of all products in cents per second - `combined_cost` number, required — Combined cost of all individual costs in cents - `llm_token_usage` object — LLM token usage of the call, available after call ends. Not populated if using custom LLM, realtime API, or no LLM call is made. - `values` number[], required — All the token count values in the call. - `average` number, required — Average token count of the call. - `num_requests` number, required — Number of requests made to the LLM. ## Other responses - `400` — Bad Request - `401` — Unauthorized - `402` — Payment Required - `422` — Unprocessable Content - `429` — Too Many Requests - `500` — Internal Server Error --- [API](https://skmtc.net/retellai/apis/retell-sdk.md) · [All operations](https://skmtc.net/retellai/apis/retell-sdk/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/retellai/retell-sdk/versions/2a182bedbfc5/schema)