Skip to main content
POST
/
v2
/
create-web-call
JavaScript
import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted
});

const webCallResponse = await client.call.createWebCall({
  agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
});

console.log(webCallResponse.agent_id);
import os
from retell import Retell

client = Retell(
    api_key=os.environ.get("RETELL_API_KEY"),  # This is the default and can be omitted
)
web_call_response = client.call.create_web_call(
    agent_id="oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
)
print(web_call_response.agent_id)
curl --request POST \
  --url https://api.retellai.com/v2/create-web-call \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "agent_version": "latest_published",
  "agent_override": {
    "agent": {
      "response_engine": {
        "type": "retell-llm",
        "llm_id": "llm_234sdertfsdsfsdf",
        "version": 0
      },
      "agent_name": "Jarvis",
      "version_description": "Customer support agent for handling product inquiries",
      "version_title": "Production hotfix",
      "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",
      "enable_expressive_mode": true,
      "expressive_emotion_tags": [
        "empathetic",
        "excited",
        "sigh",
        "clear throat",
        "emphasis"
      ],
      "expressive_mode_prompt": "Use [sigh] for thoughtful pauses and [excited] for good news.",
      "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_events": [],
      "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_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"
          ],
          "required": true,
          "conditional_prompt": "<string>"
        }
      ],
      "post_call_analysis_model": "gpt-4.1-mini",
      "begin_message_delay_ms": 1000,
      "ring_duration_ms": 30000,
      "stt_mode": "fast",
      "custom_stt_config": {
        "endpointing_ms": 123
      },
      "vocab_specialization": "general",
      "allow_user_dtmf": true,
      "allow_dtmf_interruption": false,
      "user_dtmf_options": {
        "digit_limit": 25.5,
        "termination_key": "#",
        "timeout_ms": 8000
      },
      "denoising_mode": "noise-cancellation",
      "guardrail_config": {
        "output_topics": [],
        "input_topics": [
          "platform_integrity_jailbreaking"
        ]
      },
      "handbook_config": {
        "default_personality": true,
        "conversational_personality": true,
        "natural_filler_words": true,
        "high_empathy": true,
        "echo_verification": true,
        "nato_phonetic_alphabet": true,
        "speech_normalization": true,
        "smart_matching": true,
        "ai_disclosure": true,
        "scope_boundaries": true
      },
      "timezone": "America/New_York"
    },
    "retell_llm": {
      "model": "gpt-4.1",
      "s2s_model": "gpt-realtime-1.5",
      "model_temperature": 0,
      "model_high_priority": true,
      "tool_call_strict_mode": true,
      "knowledge_base_ids": [
        "<string>"
      ],
      "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
    }
  },
  "metadata": {},
  "retell_llm_dynamic_variables": {
    "customer_name": "John Doe"
  },
  "current_node_id": "collect_info",
  "current_state": "information_collection"
}
'
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.retellai.com/v2/create-web-call",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent_id' => 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
    'agent_version' => 'latest_published',
    'agent_override' => [
        'agent' => [
                'response_engine' => [
                                'type' => 'retell-llm',
                                'llm_id' => 'llm_234sdertfsdsfsdf',
                                'version' => 0
                ],
                'agent_name' => 'Jarvis',
                'version_description' => 'Customer support agent for handling product inquiries',
                'version_title' => 'Production hotfix',
                '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',
                'enable_expressive_mode' => true,
                'expressive_emotion_tags' => [
                                'empathetic',
                                'excited',
                                'sigh',
                                'clear throat',
                                'emphasis'
                ],
                'expressive_mode_prompt' => 'Use [sigh] for thoughtful pauses and [excited] for good news.',
                '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_events' => [
                                
                ],
                '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_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'
                                                                ],
                                                                'required' => true,
                                                                'conditional_prompt' => '<string>'
                                ]
                ],
                'post_call_analysis_model' => 'gpt-4.1-mini',
                'begin_message_delay_ms' => 1000,
                'ring_duration_ms' => 30000,
                'stt_mode' => 'fast',
                'custom_stt_config' => [
                                'endpointing_ms' => 123
                ],
                'vocab_specialization' => 'general',
                'allow_user_dtmf' => true,
                'allow_dtmf_interruption' => false,
                'user_dtmf_options' => [
                                'digit_limit' => 25.5,
                                'termination_key' => '#',
                                'timeout_ms' => 8000
                ],
                'denoising_mode' => 'noise-cancellation',
                'guardrail_config' => [
                                'output_topics' => [
                                                                
                                ],
                                'input_topics' => [
                                                                'platform_integrity_jailbreaking'
                                ]
                ],
                'handbook_config' => [
                                'default_personality' => true,
                                'conversational_personality' => true,
                                'natural_filler_words' => true,
                                'high_empathy' => true,
                                'echo_verification' => true,
                                'nato_phonetic_alphabet' => true,
                                'speech_normalization' => true,
                                'smart_matching' => true,
                                'ai_disclosure' => true,
                                'scope_boundaries' => true
                ],
                'timezone' => 'America/New_York'
        ],
        'retell_llm' => [
                'model' => 'gpt-4.1',
                's2s_model' => 'gpt-realtime-1.5',
                'model_temperature' => 0,
                'model_high_priority' => true,
                'tool_call_strict_mode' => true,
                'knowledge_base_ids' => [
                                '<string>'
                ],
                '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
        ]
    ],
    'metadata' => [
        
    ],
    'retell_llm_dynamic_variables' => [
        'customer_name' => 'John Doe'
    ],
    'current_node_id' => 'collect_info',
    'current_state' => 'information_collection'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.retellai.com/v2/create-web-call"

	payload := strings.NewReader("{\n  \"agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n  \"agent_version\": \"latest_published\",\n  \"agent_override\": {\n    \"agent\": {\n      \"response_engine\": {\n        \"type\": \"retell-llm\",\n        \"llm_id\": \"llm_234sdertfsdsfsdf\",\n        \"version\": 0\n      },\n      \"agent_name\": \"Jarvis\",\n      \"version_description\": \"Customer support agent for handling product inquiries\",\n      \"version_title\": \"Production hotfix\",\n      \"voice_id\": \"retell-Cimo\",\n      \"fallback_voice_ids\": [\n        \"cartesia-Cimo\",\n        \"minimax-Cimo\"\n      ],\n      \"voice_temperature\": 1,\n      \"voice_speed\": 1,\n      \"enable_dynamic_voice_speed\": true,\n      \"enable_dynamic_responsiveness\": true,\n      \"volume\": 1,\n      \"voice_emotion\": \"calm\",\n      \"enable_expressive_mode\": true,\n      \"expressive_emotion_tags\": [\n        \"empathetic\",\n        \"excited\",\n        \"sigh\",\n        \"clear throat\",\n        \"emphasis\"\n      ],\n      \"expressive_mode_prompt\": \"Use [sigh] for thoughtful pauses and [excited] for good news.\",\n      \"responsiveness\": 1,\n      \"interruption_sensitivity\": 1,\n      \"enable_backchannel\": true,\n      \"backchannel_frequency\": 0.9,\n      \"backchannel_words\": [\n        \"yeah\",\n        \"uh-huh\"\n      ],\n      \"reminder_trigger_ms\": 10000,\n      \"reminder_max_count\": 2,\n      \"ambient_sound_volume\": 1,\n      \"language\": \"en-US\",\n      \"webhook_url\": \"https://webhook-url-here\",\n      \"webhook_events\": [],\n      \"webhook_timeout_ms\": 10000,\n      \"boosted_keywords\": [\n        \"retell\",\n        \"kroger\"\n      ],\n      \"data_storage_setting\": \"everything\",\n      \"data_storage_retention_days\": 30,\n      \"opt_in_signed_url\": true,\n      \"signed_url_expiration_ms\": 86400000,\n      \"pronunciation_dictionary\": [\n        {\n          \"word\": \"actually\",\n          \"alphabet\": \"ipa\",\n          \"phoneme\": \"ˈæktʃuəli\"\n        }\n      ],\n      \"end_call_after_silence_ms\": 600000,\n      \"max_call_duration_ms\": 3600000,\n      \"voicemail_option\": {\n        \"action\": {\n          \"type\": \"static_text\",\n          \"text\": \"Please give us a callback tomorrow at 10am.\"\n        }\n      },\n      \"ivr_option\": {\n        \"action\": {\n          \"type\": \"hangup\"\n        }\n      },\n      \"call_screening_option\": {\n        \"agent_identity\": \"Acme Health scheduling team\",\n        \"call_purpose\": \"confirming your appointment for tomorrow\"\n      },\n      \"post_call_analysis_data\": [\n        {\n          \"type\": \"string\",\n          \"name\": \"customer_name\",\n          \"description\": \"The name of the customer.\",\n          \"examples\": [\n            \"John Doe\",\n            \"Jane Smith\"\n          ],\n          \"required\": true,\n          \"conditional_prompt\": \"<string>\"\n        }\n      ],\n      \"post_call_analysis_model\": \"gpt-4.1-mini\",\n      \"begin_message_delay_ms\": 1000,\n      \"ring_duration_ms\": 30000,\n      \"stt_mode\": \"fast\",\n      \"custom_stt_config\": {\n        \"endpointing_ms\": 123\n      },\n      \"vocab_specialization\": \"general\",\n      \"allow_user_dtmf\": true,\n      \"allow_dtmf_interruption\": false,\n      \"user_dtmf_options\": {\n        \"digit_limit\": 25.5,\n        \"termination_key\": \"#\",\n        \"timeout_ms\": 8000\n      },\n      \"denoising_mode\": \"noise-cancellation\",\n      \"guardrail_config\": {\n        \"output_topics\": [],\n        \"input_topics\": [\n          \"platform_integrity_jailbreaking\"\n        ]\n      },\n      \"handbook_config\": {\n        \"default_personality\": true,\n        \"conversational_personality\": true,\n        \"natural_filler_words\": true,\n        \"high_empathy\": true,\n        \"echo_verification\": true,\n        \"nato_phonetic_alphabet\": true,\n        \"speech_normalization\": true,\n        \"smart_matching\": true,\n        \"ai_disclosure\": true,\n        \"scope_boundaries\": true\n      },\n      \"timezone\": \"America/New_York\"\n    },\n    \"retell_llm\": {\n      \"model\": \"gpt-4.1\",\n      \"s2s_model\": \"gpt-realtime-1.5\",\n      \"model_temperature\": 0,\n      \"model_high_priority\": true,\n      \"tool_call_strict_mode\": true,\n      \"knowledge_base_ids\": [\n        \"<string>\"\n      ],\n      \"kb_config\": {\n        \"top_k\": 3,\n        \"filter_score\": 0.6\n      },\n      \"begin_after_user_silence_ms\": 2000,\n      \"begin_message\": \"Hey I am a virtual assistant calling from Retell Hospital.\"\n    },\n    \"conversation_flow\": {\n      \"model_temperature\": 0.7,\n      \"tool_call_strict_mode\": true,\n      \"knowledge_base_ids\": [\n        \"kb_001\",\n        \"kb_002\"\n      ],\n      \"kb_config\": {\n        \"top_k\": 3,\n        \"filter_score\": 0.6\n      },\n      \"start_speaker\": \"agent\",\n      \"begin_after_user_silence_ms\": 2000\n    }\n  },\n  \"metadata\": {},\n  \"retell_llm_dynamic_variables\": {\n    \"customer_name\": \"John Doe\"\n  },\n  \"current_node_id\": \"collect_info\",\n  \"current_state\": \"information_collection\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.retellai.com/v2/create-web-call")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n  \"agent_version\": \"latest_published\",\n  \"agent_override\": {\n    \"agent\": {\n      \"response_engine\": {\n        \"type\": \"retell-llm\",\n        \"llm_id\": \"llm_234sdertfsdsfsdf\",\n        \"version\": 0\n      },\n      \"agent_name\": \"Jarvis\",\n      \"version_description\": \"Customer support agent for handling product inquiries\",\n      \"version_title\": \"Production hotfix\",\n      \"voice_id\": \"retell-Cimo\",\n      \"fallback_voice_ids\": [\n        \"cartesia-Cimo\",\n        \"minimax-Cimo\"\n      ],\n      \"voice_temperature\": 1,\n      \"voice_speed\": 1,\n      \"enable_dynamic_voice_speed\": true,\n      \"enable_dynamic_responsiveness\": true,\n      \"volume\": 1,\n      \"voice_emotion\": \"calm\",\n      \"enable_expressive_mode\": true,\n      \"expressive_emotion_tags\": [\n        \"empathetic\",\n        \"excited\",\n        \"sigh\",\n        \"clear throat\",\n        \"emphasis\"\n      ],\n      \"expressive_mode_prompt\": \"Use [sigh] for thoughtful pauses and [excited] for good news.\",\n      \"responsiveness\": 1,\n      \"interruption_sensitivity\": 1,\n      \"enable_backchannel\": true,\n      \"backchannel_frequency\": 0.9,\n      \"backchannel_words\": [\n        \"yeah\",\n        \"uh-huh\"\n      ],\n      \"reminder_trigger_ms\": 10000,\n      \"reminder_max_count\": 2,\n      \"ambient_sound_volume\": 1,\n      \"language\": \"en-US\",\n      \"webhook_url\": \"https://webhook-url-here\",\n      \"webhook_events\": [],\n      \"webhook_timeout_ms\": 10000,\n      \"boosted_keywords\": [\n        \"retell\",\n        \"kroger\"\n      ],\n      \"data_storage_setting\": \"everything\",\n      \"data_storage_retention_days\": 30,\n      \"opt_in_signed_url\": true,\n      \"signed_url_expiration_ms\": 86400000,\n      \"pronunciation_dictionary\": [\n        {\n          \"word\": \"actually\",\n          \"alphabet\": \"ipa\",\n          \"phoneme\": \"ˈæktʃuəli\"\n        }\n      ],\n      \"end_call_after_silence_ms\": 600000,\n      \"max_call_duration_ms\": 3600000,\n      \"voicemail_option\": {\n        \"action\": {\n          \"type\": \"static_text\",\n          \"text\": \"Please give us a callback tomorrow at 10am.\"\n        }\n      },\n      \"ivr_option\": {\n        \"action\": {\n          \"type\": \"hangup\"\n        }\n      },\n      \"call_screening_option\": {\n        \"agent_identity\": \"Acme Health scheduling team\",\n        \"call_purpose\": \"confirming your appointment for tomorrow\"\n      },\n      \"post_call_analysis_data\": [\n        {\n          \"type\": \"string\",\n          \"name\": \"customer_name\",\n          \"description\": \"The name of the customer.\",\n          \"examples\": [\n            \"John Doe\",\n            \"Jane Smith\"\n          ],\n          \"required\": true,\n          \"conditional_prompt\": \"<string>\"\n        }\n      ],\n      \"post_call_analysis_model\": \"gpt-4.1-mini\",\n      \"begin_message_delay_ms\": 1000,\n      \"ring_duration_ms\": 30000,\n      \"stt_mode\": \"fast\",\n      \"custom_stt_config\": {\n        \"endpointing_ms\": 123\n      },\n      \"vocab_specialization\": \"general\",\n      \"allow_user_dtmf\": true,\n      \"allow_dtmf_interruption\": false,\n      \"user_dtmf_options\": {\n        \"digit_limit\": 25.5,\n        \"termination_key\": \"#\",\n        \"timeout_ms\": 8000\n      },\n      \"denoising_mode\": \"noise-cancellation\",\n      \"guardrail_config\": {\n        \"output_topics\": [],\n        \"input_topics\": [\n          \"platform_integrity_jailbreaking\"\n        ]\n      },\n      \"handbook_config\": {\n        \"default_personality\": true,\n        \"conversational_personality\": true,\n        \"natural_filler_words\": true,\n        \"high_empathy\": true,\n        \"echo_verification\": true,\n        \"nato_phonetic_alphabet\": true,\n        \"speech_normalization\": true,\n        \"smart_matching\": true,\n        \"ai_disclosure\": true,\n        \"scope_boundaries\": true\n      },\n      \"timezone\": \"America/New_York\"\n    },\n    \"retell_llm\": {\n      \"model\": \"gpt-4.1\",\n      \"s2s_model\": \"gpt-realtime-1.5\",\n      \"model_temperature\": 0,\n      \"model_high_priority\": true,\n      \"tool_call_strict_mode\": true,\n      \"knowledge_base_ids\": [\n        \"<string>\"\n      ],\n      \"kb_config\": {\n        \"top_k\": 3,\n        \"filter_score\": 0.6\n      },\n      \"begin_after_user_silence_ms\": 2000,\n      \"begin_message\": \"Hey I am a virtual assistant calling from Retell Hospital.\"\n    },\n    \"conversation_flow\": {\n      \"model_temperature\": 0.7,\n      \"tool_call_strict_mode\": true,\n      \"knowledge_base_ids\": [\n        \"kb_001\",\n        \"kb_002\"\n      ],\n      \"kb_config\": {\n        \"top_k\": 3,\n        \"filter_score\": 0.6\n      },\n      \"start_speaker\": \"agent\",\n      \"begin_after_user_silence_ms\": 2000\n    }\n  },\n  \"metadata\": {},\n  \"retell_llm_dynamic_variables\": {\n    \"customer_name\": \"John Doe\"\n  },\n  \"current_node_id\": \"collect_info\",\n  \"current_state\": \"information_collection\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.retellai.com/v2/create-web-call")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n  \"agent_version\": \"latest_published\",\n  \"agent_override\": {\n    \"agent\": {\n      \"response_engine\": {\n        \"type\": \"retell-llm\",\n        \"llm_id\": \"llm_234sdertfsdsfsdf\",\n        \"version\": 0\n      },\n      \"agent_name\": \"Jarvis\",\n      \"version_description\": \"Customer support agent for handling product inquiries\",\n      \"version_title\": \"Production hotfix\",\n      \"voice_id\": \"retell-Cimo\",\n      \"fallback_voice_ids\": [\n        \"cartesia-Cimo\",\n        \"minimax-Cimo\"\n      ],\n      \"voice_temperature\": 1,\n      \"voice_speed\": 1,\n      \"enable_dynamic_voice_speed\": true,\n      \"enable_dynamic_responsiveness\": true,\n      \"volume\": 1,\n      \"voice_emotion\": \"calm\",\n      \"enable_expressive_mode\": true,\n      \"expressive_emotion_tags\": [\n        \"empathetic\",\n        \"excited\",\n        \"sigh\",\n        \"clear throat\",\n        \"emphasis\"\n      ],\n      \"expressive_mode_prompt\": \"Use [sigh] for thoughtful pauses and [excited] for good news.\",\n      \"responsiveness\": 1,\n      \"interruption_sensitivity\": 1,\n      \"enable_backchannel\": true,\n      \"backchannel_frequency\": 0.9,\n      \"backchannel_words\": [\n        \"yeah\",\n        \"uh-huh\"\n      ],\n      \"reminder_trigger_ms\": 10000,\n      \"reminder_max_count\": 2,\n      \"ambient_sound_volume\": 1,\n      \"language\": \"en-US\",\n      \"webhook_url\": \"https://webhook-url-here\",\n      \"webhook_events\": [],\n      \"webhook_timeout_ms\": 10000,\n      \"boosted_keywords\": [\n        \"retell\",\n        \"kroger\"\n      ],\n      \"data_storage_setting\": \"everything\",\n      \"data_storage_retention_days\": 30,\n      \"opt_in_signed_url\": true,\n      \"signed_url_expiration_ms\": 86400000,\n      \"pronunciation_dictionary\": [\n        {\n          \"word\": \"actually\",\n          \"alphabet\": \"ipa\",\n          \"phoneme\": \"ˈæktʃuəli\"\n        }\n      ],\n      \"end_call_after_silence_ms\": 600000,\n      \"max_call_duration_ms\": 3600000,\n      \"voicemail_option\": {\n        \"action\": {\n          \"type\": \"static_text\",\n          \"text\": \"Please give us a callback tomorrow at 10am.\"\n        }\n      },\n      \"ivr_option\": {\n        \"action\": {\n          \"type\": \"hangup\"\n        }\n      },\n      \"call_screening_option\": {\n        \"agent_identity\": \"Acme Health scheduling team\",\n        \"call_purpose\": \"confirming your appointment for tomorrow\"\n      },\n      \"post_call_analysis_data\": [\n        {\n          \"type\": \"string\",\n          \"name\": \"customer_name\",\n          \"description\": \"The name of the customer.\",\n          \"examples\": [\n            \"John Doe\",\n            \"Jane Smith\"\n          ],\n          \"required\": true,\n          \"conditional_prompt\": \"<string>\"\n        }\n      ],\n      \"post_call_analysis_model\": \"gpt-4.1-mini\",\n      \"begin_message_delay_ms\": 1000,\n      \"ring_duration_ms\": 30000,\n      \"stt_mode\": \"fast\",\n      \"custom_stt_config\": {\n        \"endpointing_ms\": 123\n      },\n      \"vocab_specialization\": \"general\",\n      \"allow_user_dtmf\": true,\n      \"allow_dtmf_interruption\": false,\n      \"user_dtmf_options\": {\n        \"digit_limit\": 25.5,\n        \"termination_key\": \"#\",\n        \"timeout_ms\": 8000\n      },\n      \"denoising_mode\": \"noise-cancellation\",\n      \"guardrail_config\": {\n        \"output_topics\": [],\n        \"input_topics\": [\n          \"platform_integrity_jailbreaking\"\n        ]\n      },\n      \"handbook_config\": {\n        \"default_personality\": true,\n        \"conversational_personality\": true,\n        \"natural_filler_words\": true,\n        \"high_empathy\": true,\n        \"echo_verification\": true,\n        \"nato_phonetic_alphabet\": true,\n        \"speech_normalization\": true,\n        \"smart_matching\": true,\n        \"ai_disclosure\": true,\n        \"scope_boundaries\": true\n      },\n      \"timezone\": \"America/New_York\"\n    },\n    \"retell_llm\": {\n      \"model\": \"gpt-4.1\",\n      \"s2s_model\": \"gpt-realtime-1.5\",\n      \"model_temperature\": 0,\n      \"model_high_priority\": true,\n      \"tool_call_strict_mode\": true,\n      \"knowledge_base_ids\": [\n        \"<string>\"\n      ],\n      \"kb_config\": {\n        \"top_k\": 3,\n        \"filter_score\": 0.6\n      },\n      \"begin_after_user_silence_ms\": 2000,\n      \"begin_message\": \"Hey I am a virtual assistant calling from Retell Hospital.\"\n    },\n    \"conversation_flow\": {\n      \"model_temperature\": 0.7,\n      \"tool_call_strict_mode\": true,\n      \"knowledge_base_ids\": [\n        \"kb_001\",\n        \"kb_002\"\n      ],\n      \"kb_config\": {\n        \"top_k\": 3,\n        \"filter_score\": 0.6\n      },\n      \"start_speaker\": \"agent\",\n      \"begin_after_user_silence_ms\": 2000\n    }\n  },\n  \"metadata\": {},\n  \"retell_llm_dynamic_variables\": {\n    \"customer_name\": \"John Doe\"\n  },\n  \"current_node_id\": \"collect_info\",\n  \"current_state\": \"information_collection\"\n}"

response = http.request(request)
puts response.read_body
{
  "call_type": "web_call",
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tSm9p",
  "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "agent_version": 1,
  "call_status": "registered",
  "agent_name": "My Agent",
  "agent_tag": "prod",
  "metadata": {},
  "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,
      "values": [
        123
      ]
    },
    "asr": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10,
      "values": [
        123
      ]
    },
    "llm": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10,
      "values": [
        123
      ]
    },
    "llm_websocket_network_rtt": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10,
      "values": [
        123
      ]
    },
    "tts": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10,
      "values": [
        123
      ]
    },
    "knowledge_base": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10,
      "values": [
        123
      ]
    },
    "s2s": {
      "p50": 800,
      "p90": 1200,
      "p95": 1500,
      "p99": 2500,
      "max": 2700,
      "min": 500,
      "num": 10,
      "values": [
        123
      ]
    }
  },
  "disconnection_reason": "agent_hangup",
  "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.",
    "in_voicemail": false,
    "user_sentiment": "Positive",
    "call_successful": true,
    "custom_analysis_data": {}
  },
  "call_cost": {
    "product_costs": [
      {
        "product": "elevenlabs_tts",
        "cost": 60,
        "unit_price": 1,
        "is_transfer_leg_cost": true
      }
    ],
    "total_duration_seconds": 60,
    "total_duration_unit_price": 1,
    "combined_cost": 70
  },
  "llm_token_usage": {
    "values": [
      123
    ],
    "average": 123,
    "num_requests": 123
  }
}
{
  "status": "error",
  "message": "Invalid request format, please check API reference."
}
{
  "status": "error",
  "message": "API key is missing or invalid."
}
{
  "status": "error",
  "message": "Trial has ended, please add payment method."
}
{
  "status": "error",
  "message": "Cannot find requested asset under given api key."
}
{
  "status": "error",
  "message": "Account rate limited, please throttle your requests."
}
{
  "status": "error",
  "message": "An unexpected server error occurred."
}

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:
{ "customer_name": "John Doe" }
​
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_type
enum<string>
required

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

Available options:
web_call
Example:

"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.

Example:

"eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tSm9p"

​
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.

Example:

"Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6"

​
agent_id
string
required

Corresponding agent id of this call.

Example:

"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD"

​
agent_version
integer
required

The version of the agent.

Example:

1

​
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 hung up, or call transferred.
  • error: Call encountered error.
Available options:
registered,
not_connected,
ongoing,
ended,
error
Example:

"registered"

​
agent_name
string

Name of the agent.

Example:

"My Agent"

​
agent_tag
string | null

Tag pointing at the agent version used for this call, captured at call creation time and frozen thereafter (unaffected by later tag reassignments). Populated whether the caller dispatched by tag, numeric version, "latest", or "latest_published" — when the caller specified a tag, that tag wins; otherwise the most-recently- assigned tag on the resolved version is used. Absent when no tag points at the resolved version (or for calls created before this field was introduced).

Example:

"prod"

​
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:
{ "customer_name": "John Doe" }
​
collected_dynamic_variables
object

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

Example:
{ "last_node_name": "Test node" }
​
custom_sip_headers
object

Custom SIP headers to be added to the call.

Example:
{ "X-Custom-Header": "Custom Value" }
​
data_storage_setting
enum<string> | null

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.

Available options:
everything,
everything_except_pii,
basic_attributes_only
Example:

"everything"

​
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.

Example:

true

​
start_timestamp
integer

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

Example:

1703302407333

​
end_timestamp
integer

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

Example:

1703302428855

​
transfer_end_timestamp
integer

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

Example:

1703302628855

​
duration_ms
integer

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

Example:

10000

​
transcript
string

Transcription of the call. Available after call ends.

Example:

"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
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.

​
scrubbed_transcript_with_tool_calls
object[]

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.

​
recording_url
string

Recording of the call. Available after call ends.

Example:

"https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav"

​
recording_multi_channel_url
string

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

Example:

"https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav"

​
scrubbed_recording_url
string

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

Example:

"https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav"

​
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.

Example:

"https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav"

​
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.

Example:

"https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/public_log.txt"

​
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.

Example:

"https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/kb_retrieved_contents.txt"

​
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.

​
disconnection_reason
enum<string>

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

Available options:
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,
call_take_over
Example:

"agent_hangup"

​
transfer_destination
string | null

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:

"+12137771234"

​
call_analysis
object

Post call analysis that includes information such as sentiment, status, summary, and custom defined data to extract. Available after call ends. Subscribe to call_analyzed webhook event type to receive it once ready.

​
call_cost
object

Cost of the call, including all the products and their costs and discount.

​
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.