POST /create-batch-call – Retell AI Retell SDK

Create a batch call

post/create-batch-call

Request body

namestring

The name of the batch call. Only used for your own reference.

trigger_timestampnumber

The scheduled time for sending the batch call, represented as a Unix timestamp in milliseconds. If omitted, the call will be sent immediately.

from_numberstring required

The number you own in E.164 format. Must be a number purchased from Retell or imported to Retell.

reserved_concurrencyinteger

Number of concurrency reserved for all other calls that are not triggered by batch calls, such as inbound calls.

Example request

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

Response

Successfully created a batch call.

batch_call_idstring required

Unique id of the batch call.

namestring required

from_numberstring required

scheduled_timestampnumber required

total_task_countnumber required

Number of tasks within the batch call

Example response

{
  "batch_call_id": "batch_call_dbcc4412483ebfc348abb",
  "name": "First batch call",
  "from_number": "+14157774444",
  "scheduled_timestamp": 1735718400,
  "call_time_window": {
    "windows": [
      {
        "start": 540,
        "end": 1020
      }
    ]
  }
}

Changes

Changed in 20 of the 28 revisions of this API.881360

May 28, 202640402ca870b91See the full diff
- ●
  changed the pattern of the request property /// from ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ to ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$
  request-property-pattern-changed
May 18, 20266342a99901081See the full diff
- ●
  removed the request property ////
  request-property-removed
May 12, 20266dff2a12f8661See the full diff
- ▲
  the /// request property type changed from no type to string
  request-property-type-changed
May 11, 20267c30e3ea25363See the full diff
- ○
  added the new gpt-realtime-2 enum value to the request property ////
  request-property-enum-value-added
- ○
  added the new s2.1-pro enum value to the request property ////
  request-property-enum-value-added
- ○
  added the new sonic-3.5 enum value to the request property ////
  request-property-enum-value-added
May 8, 20267dd16ddf69d81See the full diff
- ●
  changed the pattern of the request property /// from ^[a-z0-9_-]+$ to ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$
  request-property-pattern-changed
May 7, 2026f1a0d7c1e36c35See the full diff
- ▲
  removed the enum value gemini-2.5-flash of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value gemini-2.5-flash of the request property /////////
  request-property-enum-value-removed
- ▲
  removed the enum value gemini-2.5-flash of the request property ////
  request-property-enum-value-removed
- ○
  added the new optional request property ////
  new-optional-request-property
- ○
  added the new optional request property ////
  new-optional-request-property
- ○
  added the new optional request property /////
  new-optional-request-property
- ○
  added the new optional request property /////
  new-optional-request-property
- ○
  request property // list-of-types was widened by adding types string to media type application/json
  request-property-list-of-types-widened
Apr 28, 20261b4a9d84942a53See the full diff
- ▲
  added to the ///// request property allOf list
  request-property-all-of-added
- ▲
  removed the enum value azure of the request property /////
  request-property-enum-value-removed
- ▲
  removed the enum value deepgram of the request property /////
  request-property-enum-value-removed
- ▲
  removed the enum value soniox of the request property /////
  request-property-enum-value-removed
- ▲
  the ///// request property type changed from string to no type
  request-property-type-changed
- ○
  added the new gpt-5.5 enum value to the request property ////
  request-property-enum-value-added
- ○
  added the new gpt-5.5 enum value to the request property /////////
  request-property-enum-value-added
- ○
  added the new gpt-5.5 enum value to the request property ////
  request-property-enum-value-added
Apr 27, 2026a44406f743c2651See the full diff
- ▲
  removed the enum value af-ZA of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value ar-SA of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value az-AZ of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value bg-BG of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value bs-BA of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value ca-ES of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value cs-CZ of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value cy-GB of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value da-DK of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value de-DE of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value el-GR of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value en-AU of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value en-GB of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value en-IN of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value en-NZ of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value en-US of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value es-419 of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value es-ES of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value fa-IR of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value fi-FI of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value fil-PH of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value fr-CA of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value fr-FR of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value gl-ES of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value he-IL of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value hi-IN of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value hr-HR of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value hu-HU of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value hy-AM of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value id-ID of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value is-IS of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value it-IT of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value ja-JP of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value kk-KZ of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value kn-IN of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value ko-KR of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value lt-LT of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value lv-LV of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value mk-MK of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value mr-IN of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value ms-MY of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value multi of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value ne-NP of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value nl-BE of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value nl-NL of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value no-NO of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value pl-PL of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value pt-BR of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value pt-PT of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value ro-RO of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value ru-RU of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value sk-SK of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value sl-SI of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value sr-RS of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value sv-SE of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value sw-KE of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value ta-IN of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value th-TH of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value tr-TR of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value uk-UA of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value ur-IN of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value vi-VN of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value yue-CN of the request property ////
  request-property-enum-value-removed
- ▲
  removed the enum value zh-CN of the request property ////
  request-property-enum-value-removed
- ▲
  the //// request property type changed from string to no type
  request-property-type-changed
- ○
  added subschema #2 to the //// request property oneOf list
  request-property-one-of-added
Apr 20, 20268ee53928bf3115See the full diff
- ●
  removed the request property ////
  request-property-removed
- ○
  added the new gemini-3.1-flash-lite enum value to the request property ////
  request-property-enum-value-added
- ○
  added the new gemini-3.1-flash-lite enum value to the request property /////////
  request-property-enum-value-added
- ○
  added the new gemini-3.1-flash-lite enum value to the request property ////
  request-property-enum-value-added
- ○
  added the new s2-pro enum value to the request property ////
  request-property-enum-value-added
- ○
  added the new soniox enum value to the request property /////
  request-property-enum-value-added
Apr 1, 202656de19127afb13See the full diff
- ▲
  removed from the ///// request property oneOf list
  request-property-one-of-removed
- ○
  added the new optional request property ////
  new-optional-request-property
- ○
  added the new optional request property ////
  new-optional-request-property
- ○
  added to the ///// request property oneOf list
  request-property-one-of-added

Full history (20 revisions)