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 batchCallResponse = await client.batchCall.createBatchCall({
from_number: '+14157774444',
tasks: [{ to_number: '+12137774445' }],
});
console.log(batchCallResponse.batch_call_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
)
batch_call_response = client.batch_call.create_batch_call(
from_number="+14157774444",
tasks=[{
"to_number": "+12137774445"
}],
)
print(batch_call_response.batch_call_id)curl --request POST \
--url https://api.retellai.com/create-batch-call \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"from_number": "+14157774444",
"tasks": [
{
"to_number": "+12137774445",
"ignore_e164_validation": false,
"override_agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
"override_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
}
},
"retell_llm_dynamic_variables": {
"customer_name": "John Doe"
},
"metadata": {},
"custom_sip_headers": {
"X-Custom-Header": "Custom Value"
}
}
],
"name": "First batch call",
"trigger_timestamp": 1735718400000,
"reserved_concurrency": 1
}
'<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.retellai.com/create-batch-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([
'from_number' => '+14157774444',
'tasks' => [
[
'to_number' => '+12137774445',
'ignore_e164_validation' => false,
'override_agent_id' => 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
'override_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
]
],
'retell_llm_dynamic_variables' => [
'customer_name' => 'John Doe'
],
'metadata' => [
],
'custom_sip_headers' => [
'X-Custom-Header' => 'Custom Value'
]
]
],
'name' => 'First batch call',
'trigger_timestamp' => 1735718400000,
'reserved_concurrency' => 1
]),
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/create-batch-call"
payload := strings.NewReader("{\n \"from_number\": \"+14157774444\",\n \"tasks\": [\n {\n \"to_number\": \"+12137774445\",\n \"ignore_e164_validation\": false,\n \"override_agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n \"override_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 \"retell_llm_dynamic_variables\": {\n \"customer_name\": \"John Doe\"\n },\n \"metadata\": {},\n \"custom_sip_headers\": {\n \"X-Custom-Header\": \"Custom Value\"\n }\n }\n ],\n \"name\": \"First batch call\",\n \"trigger_timestamp\": 1735718400000,\n \"reserved_concurrency\": 1\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/create-batch-call")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"from_number\": \"+14157774444\",\n \"tasks\": [\n {\n \"to_number\": \"+12137774445\",\n \"ignore_e164_validation\": false,\n \"override_agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n \"override_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 \"retell_llm_dynamic_variables\": {\n \"customer_name\": \"John Doe\"\n },\n \"metadata\": {},\n \"custom_sip_headers\": {\n \"X-Custom-Header\": \"Custom Value\"\n }\n }\n ],\n \"name\": \"First batch call\",\n \"trigger_timestamp\": 1735718400000,\n \"reserved_concurrency\": 1\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.retellai.com/create-batch-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 \"from_number\": \"+14157774444\",\n \"tasks\": [\n {\n \"to_number\": \"+12137774445\",\n \"ignore_e164_validation\": false,\n \"override_agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n \"override_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 \"retell_llm_dynamic_variables\": {\n \"customer_name\": \"John Doe\"\n },\n \"metadata\": {},\n \"custom_sip_headers\": {\n \"X-Custom-Header\": \"Custom Value\"\n }\n }\n ],\n \"name\": \"First batch call\",\n \"trigger_timestamp\": 1735718400000,\n \"reserved_concurrency\": 1\n}"
response = http.request(request)
puts response.read_body{
"batch_call_id": "batch_call_dbcc4412483ebfc348abb",
"name": "First batch call",
"from_number": "+14157774444",
"scheduled_timestamp": 1735718400,
"total_task_count": 123,
"call_time_window": {
"windows": [
{
"start": 540,
"end": 1020
}
],
"timezone": "<string>",
"day": []
}
}{
"status": "error",
"message": "Invalid request format, please check API reference."
}{
"status": "error",
"message": "API key is missing or invalid."
}{
"status": "error",
"message": "Cannot find requested asset under given api key."
}{
"status": "error",
"message": "An unexpected server error occurred."
}Batch call
Create Batch Call
Create a batch call
POST
/
create-batch-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 batchCallResponse = await client.batchCall.createBatchCall({
from_number: '+14157774444',
tasks: [{ to_number: '+12137774445' }],
});
console.log(batchCallResponse.batch_call_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
)
batch_call_response = client.batch_call.create_batch_call(
from_number="+14157774444",
tasks=[{
"to_number": "+12137774445"
}],
)
print(batch_call_response.batch_call_id)curl --request POST \
--url https://api.retellai.com/create-batch-call \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"from_number": "+14157774444",
"tasks": [
{
"to_number": "+12137774445",
"ignore_e164_validation": false,
"override_agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
"override_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
}
},
"retell_llm_dynamic_variables": {
"customer_name": "John Doe"
},
"metadata": {},
"custom_sip_headers": {
"X-Custom-Header": "Custom Value"
}
}
],
"name": "First batch call",
"trigger_timestamp": 1735718400000,
"reserved_concurrency": 1
}
'<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.retellai.com/create-batch-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([
'from_number' => '+14157774444',
'tasks' => [
[
'to_number' => '+12137774445',
'ignore_e164_validation' => false,
'override_agent_id' => 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD',
'override_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
]
],
'retell_llm_dynamic_variables' => [
'customer_name' => 'John Doe'
],
'metadata' => [
],
'custom_sip_headers' => [
'X-Custom-Header' => 'Custom Value'
]
]
],
'name' => 'First batch call',
'trigger_timestamp' => 1735718400000,
'reserved_concurrency' => 1
]),
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/create-batch-call"
payload := strings.NewReader("{\n \"from_number\": \"+14157774444\",\n \"tasks\": [\n {\n \"to_number\": \"+12137774445\",\n \"ignore_e164_validation\": false,\n \"override_agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n \"override_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 \"retell_llm_dynamic_variables\": {\n \"customer_name\": \"John Doe\"\n },\n \"metadata\": {},\n \"custom_sip_headers\": {\n \"X-Custom-Header\": \"Custom Value\"\n }\n }\n ],\n \"name\": \"First batch call\",\n \"trigger_timestamp\": 1735718400000,\n \"reserved_concurrency\": 1\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/create-batch-call")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"from_number\": \"+14157774444\",\n \"tasks\": [\n {\n \"to_number\": \"+12137774445\",\n \"ignore_e164_validation\": false,\n \"override_agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n \"override_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 \"retell_llm_dynamic_variables\": {\n \"customer_name\": \"John Doe\"\n },\n \"metadata\": {},\n \"custom_sip_headers\": {\n \"X-Custom-Header\": \"Custom Value\"\n }\n }\n ],\n \"name\": \"First batch call\",\n \"trigger_timestamp\": 1735718400000,\n \"reserved_concurrency\": 1\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.retellai.com/create-batch-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 \"from_number\": \"+14157774444\",\n \"tasks\": [\n {\n \"to_number\": \"+12137774445\",\n \"ignore_e164_validation\": false,\n \"override_agent_id\": \"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD\",\n \"override_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 \"retell_llm_dynamic_variables\": {\n \"customer_name\": \"John Doe\"\n },\n \"metadata\": {},\n \"custom_sip_headers\": {\n \"X-Custom-Header\": \"Custom Value\"\n }\n }\n ],\n \"name\": \"First batch call\",\n \"trigger_timestamp\": 1735718400000,\n \"reserved_concurrency\": 1\n}"
response = http.request(request)
puts response.read_body{
"batch_call_id": "batch_call_dbcc4412483ebfc348abb",
"name": "First batch call",
"from_number": "+14157774444",
"scheduled_timestamp": 1735718400,
"total_task_count": 123,
"call_time_window": {
"windows": [
{
"start": 540,
"end": 1020
}
],
"timezone": "<string>",
"day": []
}
}{
"status": "error",
"message": "Invalid request format, please check API reference."
}{
"status": "error",
"message": "API key is missing or invalid."
}{
"status": "error",
"message": "Cannot find requested asset under given api key."
}{
"status": "error",
"message": "An unexpected server error occurred."
}Authorizations
Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"
Body
application/json
The number you own in E.164 format. Must be a number purchased from Retell or imported to Retell.
Minimum string length:
1Example:
"+14157774444"
A list of individual call tasks to be executed as part of the batch call. Each task represents a single outbound call and includes details such as the recipient's phone number and optional dynamic variables to personalize the call content.
Show child attributes
Show child attributes
The name of the batch call. Only used for your own reference.
Example:
"First batch call"
The scheduled time for sending the batch call, represented as a Unix timestamp in milliseconds. If omitted, the call will be sent immediately.
Example:
1735718400000
Number of concurrency reserved for all other calls that are not triggered by batch calls, such as inbound calls.
Required range:
x >= 0Allowed calling windows in a specific timezone. Each window is a half-open interval [startMin, endMin) in minutes since 00:00 local time. Cross-midnight windows are NOT allowed (must satisfy startMin < endMin). endMin = 1440 (24:00) is valid.
Show child attributes
Show child attributes
Response
Successfully created a batch call.
Unique id of the batch call.
Example:
"batch_call_dbcc4412483ebfc348abb"
Example:
"First batch call"
Example:
"+14157774444"
Example:
1735718400
Number of tasks within the batch call
Canonicalized minutes-based time windows. Present only if specified when the batch call was created or updated. See CallTimeWindow for format details ([startMin, endMin) in local minutes; no cross-midnight).
Show child attributes
Show child attributes
Was this page helpful?
⌘I