> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Batch-Call-Anfrage senden.

POST https://api.elevenlabs.io/v1/convai/batch-calling/submit
Content-Type: application/json

Senden Sie eine Batch-Anrufanfrage, um Anrufe für mehrere Empfänger zu planen.

Reference: https://elevenlabs.io/docs/eleven-agents/api-reference/batch-calling/create

## Servers

- `https://api.elevenlabs.io` (Production, default)
- `https://api.us.elevenlabs.io` (Production US)
- `https://api.eu.residency.elevenlabs.io` (Production EU)
- `https://api.in.residency.elevenlabs.io` (Production India)
- `https://api.sg.residency.elevenlabs.io` (Production Singapore)

## Request

### Body (application/json)

This endpoint expects an object.

- `call_name` (string, required)
- `agent_id` (string, required)
- `recipients` (list of OutboundCallRecipient, required)
- `scheduled_time_unix` (integer, optional)
- `agent_phone_number_id` (string, optional)
- `whatsapp_params` (BatchCallWhatsAppParams, optional)
- `timezone` (string, optional)
- `branch_id` (string, optional)
- `environment` (string, optional)
- `telephony_call_config` (TelephonyCallConfigInput, optional)
- `target_concurrency_limit` (integer, optional) — Maximale Anzahl gleichzeitiger Anrufe für diesen Batch. Wenn festgelegt, wird die Verteilung durch dieses Limit statt durch Kapazitätsprozentsätze von Workspace oder Agent gesteuert.

## Response

### 200

Erfolgreiche Antwort

- `id` (string, required)
- `name` (string, required)
- `agent_id` (string, required)
- `created_at_unix` (integer, required)
- `scheduled_time_unix` (integer, required)
- `total_calls_dispatched` (integer, required, default: 0)
- `total_calls_scheduled` (integer, required, default: 0)
- `total_calls_finished` (integer, required, default: 0)
- `last_updated_at_unix` (integer, required)
- `status` (enum, required)
  - Allowed values: `pending`, `in_progress`, `completed`, `failed`, `cancelled`
- `retry_count` (integer, required, default: 0)
- `telephony_call_config` (TelephonyCallConfigOutput, required)
- `agent_name` (string, required)
- `phone_number_id` (string, optional)
- `phone_provider` (enum, optional)
  - Allowed values: `twilio`, `sip_trunk`, `exotel`
- `whatsapp_params` (BatchCallWhatsAppParams, optional)
- `branch_id` (string, optional)
- `environment` (string, optional)
- `timezone` (string, optional)
- `target_concurrency_limit` (integer, optional) — Maximale Anzahl gleichzeitiger Anrufe für diesen Batch. Wenn festgelegt, wird die Verteilung durch dieses Limit statt durch Kapazitätsprozentsätze von Workspace oder Agent gesteuert.
- `branch_name` (string, optional)

## Errors

### 422 Batch Calls Create Request Unprocessable Entity Error

Validierungsfehler

- `detail` (list of ValidationError, optional)

## Types

### OutboundCallRecipient

- `id` (string, optional)
- `phone_number` (string, optional)
- `whatsapp_user_id` (string, optional)
- `conversation_initiation_client_data` (ConversationInitiationClientDataRequestInput, optional)

### BatchCallWhatsAppParams

- `whatsapp_call_permission_request_template_name` (string, required)
- `whatsapp_call_permission_request_template_language_code` (string, required)
- `whatsapp_phone_number_id` (string, optional)

### TelephonyCallConfigInput

- `ringing_timeout_secs` (integer, optional, default: 60) — Wie lange der Empfänger vor dem Abbruch in Sekunden klingeln soll. Beachten Sie, dass dies auch durch die Einschränkungen des Anbieters begrenzt wird.
- `twilio_call_recording_enabled` (boolean, optional, default: false) — Ob der Anruf mit der Anrufaufzeichnung von Twilio aufgezeichnet werden soll. Wird für Anbieter außer Twilio ignoriert. Aufzeichnungen werden in Ihrem Twilio-Konto gespeichert.
- `twilio_machine_detection` (TwilioMachineDetectionConfig, optional) — Konfiguration für Twilios netzbetreiberseitige Anrufbeantwortererkennung (AMD). Weglassen oder auf null setzen, um sie zu deaktivieren. Wird für andere Anbieter als Twilio und für eingehende Anrufe ignoriert. Das Ergebnis wird als eigenes Webhook-Ereignis `answering_machine_detection` übermittelt. Dafür muss dieses Ereignis in den Webhook-Einstellungen des Workspace oder Agents aktiviert sein; es ist nicht Teil der Unterhaltung oder des Post-Call-Webhooks. Die Erkennung läuft asynchron und verzögert daher nie den Beginn der Unterhaltung. Das Ergebnis kann zu jedem Zeitpunkt während des Anrufs eintreffen -- mit `detect_message_end` sogar nach dessen Ende. Twilio berechnet AMD separat.

### TelephonyCallConfigOutput

- `ringing_timeout_secs` (integer, optional, default: 60) — Wie lange der Empfänger vor dem Abbruch in Sekunden klingeln soll. Beachten Sie, dass dies auch durch die Einschränkungen des Anbieters begrenzt wird.
- `twilio_call_recording_enabled` (boolean, optional, default: false) — Ob der Anruf mit der Anrufaufzeichnung von Twilio aufgezeichnet werden soll. Wird für Anbieter außer Twilio ignoriert. Aufzeichnungen werden in Ihrem Twilio-Konto gespeichert.
- `twilio_machine_detection` (TwilioMachineDetectionConfig, optional) — Konfiguration für Twilios netzbetreiberseitige Anrufbeantwortererkennung (AMD). Weglassen oder auf null setzen, um sie zu deaktivieren. Wird für andere Anbieter als Twilio und für eingehende Anrufe ignoriert. Das Ergebnis wird als eigenes Webhook-Ereignis `answering_machine_detection` übermittelt. Dafür muss dieses Ereignis in den Webhook-Einstellungen des Workspace oder Agents aktiviert sein; es ist nicht Teil der Unterhaltung oder des Post-Call-Webhooks. Die Erkennung läuft asynchron und verzögert daher nie den Beginn der Unterhaltung. Das Ergebnis kann zu jedem Zeitpunkt während des Anrufs eintreffen -- mit `detect_message_end` sogar nach dessen Ende. Twilio berechnet AMD separat.

### ValidationError

- `loc` (list of ValidationErrorLocItem, required)
- `msg` (string, required)
- `type` (string, required)

### ConversationInitiationClientDataRequestInput

- `conversation_config_override` (ConversationConfigClientOverrideInput, optional)
- `custom_llm_extra_body` (map from string to any, optional)
- `user_id` (string, optional) — ID des Endnutzers, der an dieser Unterhaltung teilnimmt (zur Nutzeridentifikation des Agent-Eigentümers)
- `source_info` (ConversationInitiationSourceInfo, optional) — Informationen über die Quelle der Gesprächsinitiierung
- `branch_id` (string, optional) — ID des Agent-Branches, der für diese Unterhaltung verwendet werden soll
- `environment` (string, optional) — Umgebung zum Auflösen von Umgebungsvariablen
- `starting_workflow_node_id` (string, optional) — Falls gesetzt, startet der Workflow an dieser Knoten-ID statt am Standardeinstieg.
- `procedure_ids` (list of string, optional) — Wenn gesetzt, stehen dem startenden Agenten nur diese Prozeduren zur Verfügung. Jede ID muss diesem Agenten zugeordnet sein. Unbekannte IDs verhindern den Start der Unterhaltung. Eine leere Liste deaktiviert alle Prozeduren dieses Agenten. Wird nach einer Agentenübertragung nicht angewendet. Erfordert enable_procedure_ids_from_client.
- `dynamic_variables` (map from string to any, optional)

### TwilioMachineDetectionConfig

Wie Twilios netzbetreiberseitige Anrufbeantwortererkennung (AMD) bei einem Anruf ausgeführt wird.

- `mode` (enum, optional, default: enable) — Wie gründlich die Erkennung sein soll. `enable` gibt ein Ergebnis zurück, sobald Twilio einen Menschen von einer Maschine unterscheiden kann. `detect_message_end` wartet außerdem, bis die Mailboxansage beendet ist, wodurch die Ergebnisse `machine_end_*` erzeugt werden, liefert aber später ein Ergebnis.
  - Allowed values: `enable`, `detect_message_end`

### ValidationErrorLocItem

### ConversationConfigClientOverrideInput

- `asr` (AsrConversationalConfigOverride, optional) — Konfiguration für Transkription in Unterhaltungen
- `turn` (TurnConfigOverride, optional) — Konfiguration für Sprecherwechselerkennung
- `tts` (TtsConversationalConfigOverride, optional) — Konfiguration für Text to Speech in Unterhaltungen
- `conversation` (ConversationConfigOverride, optional) — Konfiguration für Unterhaltungsereignisse
- `agent` (AgentConfigOverrideInput, optional) — Agent-spezifische Konfiguration

### ConversationInitiationSourceInfo

Informationen über die Quelle der Gesprächsinitiierung

- `source` (enum, optional, default: unknown) — Quelle der Gesprächsinitiierung
  - Allowed values: `unknown`, `android_sdk`, `node_js_sdk`, `react_native_sdk`, `react_sdk`, `js_sdk`, `python_sdk`, `widget`, `sip_trunk`, `twilio`, `exotel`, `genesys`, `avaya`, `audiocodes`, `swift_sdk`, `whatsapp`, `twilio_sms`, `flutter_sdk`, `zendesk_integration`, `slack_integration`, `telegram_integration`, `intercom_integration`, `freshdesk_integration`, `salesforce_integration`, `template_preview`, `genesys_bot_connector`, `subagent_tool`
- `version` (string, optional) — Die SDK-Versionsnummer

### AsrConversationalConfigOverride

- `keywords` (list of string, optional) — Schlüsselwörter, deren Vorhersagewahrscheinlichkeit erhöht werden soll

### TurnConfigOverride

- `soft_timeout_config` (SoftTimeoutConfigOverride, optional) — Konfiguration für die Soft-Timeout-Funktion. Liefert sofortiges Feedback bei längeren LLM-Antworten.

### TtsConversationalConfigOverride

- `model_id` (enum, optional, default: eleven_v4_turbo) — Das für TTS zu verwendende Modell
  - Allowed values: `eleven_turbo_v2`, `eleven_turbo_v2_5`, `eleven_flash_v2`, `eleven_flash_v2_5`, `eleven_multilingual_v2`, `eleven_v3_conversational`, `eleven_v4`, `eleven_v4_turbo`
- `voice_id` (string, optional) — Die für TTS zu verwendende Stimmen-ID
- `supported_voices` (list of SupportedVoice, optional) — Zusätzlich unterstützte Stimmen für den Agenten
- `stability` (double, optional) — Die Stabilität der generierten Sprache
- `speed` (double, optional) — Die Geschwindigkeit der generierten Sprache
- `similarity_boost` (double, optional) — Der Ähnlichkeits-Boost für generierte Sprache
- `pronunciation_dictionary_locators` (list of PydanticPronunciationDictionaryVersionLocator, optional) — Die Referenzen auf Aussprachewörterbücher

### ConversationConfigOverride

- `text_only` (boolean, optional) — Wenn aktiviert, wird Audio nicht verarbeitet und nur Text verwendet. Verwenden Sie dies, um Audiokosten zu vermeiden.
- `max_duration_seconds` (integer, optional) — Die maximale Dauer einer Unterhaltung in Sekunden

### AgentConfigOverrideInput

- `first_message` (string, optional) — Wenn nicht leer, die erste Nachricht, die der Agent sagt. Wenn leer, wartet der Agent, bis der Nutzer die Unterhaltung beginnt.
- `language` (string, optional) — Sprache des Agenten – verwendet für ASR und TTS
- `max_conversation_duration_message` (string, optional) — Wenn nicht leer, die Nachricht, die der Agent sendet, wenn die maximale Gesprächsdauer erreicht ist.
- `prompt` (PromptAgentApiModelOverrideInput, optional) — Der Prompt für den Agenten

### SoftTimeoutConfigOverride

- `message` (string, optional) — Nachricht, die angezeigt wird, wenn beim Warten auf die LLM-Antwort der erste weiche Timeout erreicht wird. Unterstützt dynamische Variablen (z. B. \{\{system\_\_time}}, \{\{custom\_variable}}).
- `additional_soft_timeout_messages` (list of string, optional) — Zusätzliche statische Füllnachrichten für nachfolgende Soft-Timeouts in derselben LLM-Generierung. Das erste Timeout verwendet `message`. Wenn weniger Nachrichten als `max_soft_timeouts_per_generation` konfiguriert sind, wird die zuletzt konfigurierte Nachricht wiederholt; andernfalls wird eine integrierte Füllnachricht verwendet.

### SupportedVoice

- `label` (string, required)
- `voice_id` (string, required)
- `description` (string, optional)
- `language` (string, optional)
- `model_family` (enum, optional)
  - Allowed values: `turbo`, `flash`, `multilingual`, `v3_conversational`, `v4`, `v4_turbo`
- `optimize_streaming_latency` (integer, optional)
- `stability` (double, optional)
- `speed` (double, optional)
- `similarity_boost` (double, optional)

### PydanticPronunciationDictionaryVersionLocator

Eine Referenz, damit andere Dokumente auf ein bestimmtes Wörterbuch und dessen Version verweisen können. Dies ist eine Pydantic-Version von PronunciationDictionaryVersionLocatorDBModel. Erforderlich, um die Kompatibilität mit den übrigen Agent-Datenmodellen sicherzustellen.

- `pronunciation_dictionary_id` (string, required) — Die ID des Aussprachewörterbuchs
- `version_id` (string, optional) — Die ID der Version des Aussprachewörterbuchs

### PromptAgentApiModelOverrideInput

- `prompt` (string, optional) — Der Prompt für den Agenten
- `llm` (enum, optional) — Das LLM, das mit dem Prompt und dem Chatverlauf abgefragt wird. Bei Verwendung von Datenresidenz muss das LLM in der Datenresidenzumgebung unterstützt werden.
  - Allowed values: `gpt-4o-mini`, `gpt-4o`, `gpt-4`, `gpt-4-turbo`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, `gpt-5`, `gpt-5.1`, `gpt-5.2`, `gpt-5.2-chat-latest`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-6-astra`, `gpt-6-sol`, `gpt-6-luna`, `gpt-6.1-sol`, `gpt-5-mini`, `gpt-5-nano`, `gpt-3.5-turbo`, `gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-2.0-flash`, `gemini-2.0-flash-lite`, `gemini-2.5-flash-lite`, `gemini-2.5-flash`, `gemini-3-pro-preview`, `gemini-3-flash-preview`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3.1-flash-lite`, `gemini-3.5-flash`, `gemini-3.5-flash-lite`, `gemini-3.6-flash`, `gemini-3.7-flash`, `gemini-3.8-flash`, `gemini-4-argon`, `claude-sonnet-4-5`, `claude-opus-4-6`, `claude-opus-4-7`, `claude-opus-4-8`, `claude-opus-5`, `claude-opus-5-5`, `claude-sonnet-4-6`, `claude-sonnet-5`, `claude-sonnet-5-5`, `claude-sonnet-4`, `claude-haiku-4-5`, `claude-haiku-5-5`, `claude-3-7-sonnet`, `claude-3-5-sonnet`, `claude-3-5-sonnet-v1`, `claude-3-haiku`, `grok-beta`, `custom-llm`, `qwen3-4b`, `qwen3-30b-a3b`, `qwen36-35b-a3b`, `qwen35-397b-a17b`, `gpt-oss-20b`, `gpt-oss-120b`, `glm-45-air-fp8`, `glm-52`, `deepseek-v41-flash`, `nemotron-35-super-vl-nvfp4`, `gemini-2.5-flash-preview-09-2025`, `gemini-2.5-flash-lite-preview-09-2025`, `gemini-2.5-flash-preview-05-20`, `gemini-2.5-flash-preview-04-17`, `gemini-2.5-flash-lite-preview-06-17`, `gemini-2.0-flash-lite-001`, `gemini-2.0-flash-001`, `gemini-1.5-flash-002`, `gemini-1.5-flash-001`, `gemini-1.5-pro-002`, `gemini-1.5-pro-001`, `claude-sonnet-4@20250514`, `claude-sonnet-4-5@20250929`, `claude-haiku-4-5@20251001`, `claude-3-7-sonnet@20250219`, `claude-3-5-sonnet@20240620`, `claude-3-5-sonnet-v2@20241022`, `claude-3-haiku@20240307`, `gpt-5-2025-08-07`, `gpt-5.1-2025-11-13`, `gpt-5.2-2025-12-11`, `gpt-5.4-2026-03-05`, `gpt-5.4-mini-2026-03-17`, `gpt-5.4-nano-2026-03-17`, `gpt-5.5-2026-04-23`, `gpt-5-mini-2025-08-07`, `gpt-5-nano-2025-08-07`, `gpt-4.1-2025-04-14`, `gpt-4.1-mini-2025-04-14`, `gpt-4.1-nano-2025-04-14`, `gpt-4o-mini-2024-07-18`, `gpt-4o-2024-11-20`, `gpt-4o-2024-08-06`, `gpt-4o-2024-05-13`, `gpt-4-0613`, `gpt-4-0314`, `gpt-4-turbo-2024-04-09`, `gpt-3.5-turbo-0125`, `gpt-3.5-turbo-1106`, `watt-tool-8b`, `watt-tool-70b`
- `tool_ids` (list of string, optional) — Eine Liste der IDs von Tools, die der Agent verwendet
- `tool_ids_strict` (boolean, optional) — Gilt nur als Überschreibung für eine Unterhaltung und ist zulässig, wenn tool_ids überschrieben werden dürfen. Wenn true, enthält die überschreibende tool_ids die vollständige Liste der in der Unterhaltung erlaubten Tools, einschließlich der Tools in Workflow-Knoten. Wird ignoriert, wenn es für den Agenten festgelegt ist.
- `native_mcp_server_ids` (list of string, optional) — Eine Liste der nativen MCP-Server-IDs, die der Agent verwenden soll
- `knowledge_base` (list of KnowledgeBaseLocator, optional) — Eine Liste der Wissensdatenbanken, die der Agent verwenden soll

### KnowledgeBaseLocator

- `type` (enum, required) — Der Typ der Wissensdatenbank
  - Allowed values: `file`, `url`, `text`, `folder`
- `name` (string, required) — Der Name der Wissensdatenbank
- `id` (string, required) — Die ID der Wissensdatenbank
- `usage_mode` (enum, optional, default: auto) — Der Nutzungsmodus der Wissensdatenbank
  - Allowed values: `prompt`, `auto`

## Examples

**Request**

```json
{
  "call_name": "call_name",
  "agent_id": "agent_id",
  "recipients": [
    {}
  ]
}
```

**Response**

```json
{
  "id": "id",
  "name": "name",
  "agent_id": "agent_id",
  "created_at_unix": 1,
  "scheduled_time_unix": 1,
  "total_calls_dispatched": 1,
  "total_calls_scheduled": 1,
  "total_calls_finished": 1,
  "last_updated_at_unix": 1,
  "status": "pending",
  "retry_count": 1,
  "telephony_call_config": {
    "ringing_timeout_secs": 1,
    "twilio_call_recording_enabled": true,
    "twilio_machine_detection": {
      "mode": "enable"
    }
  },
  "agent_name": "agent_name",
  "phone_number_id": "phone_number_id",
  "phone_provider": "twilio",
  "whatsapp_params": {
    "whatsapp_call_permission_request_template_name": "whatsapp_call_permission_request_template_name",
    "whatsapp_call_permission_request_template_language_code": "whatsapp_call_permission_request_template_language_code",
    "whatsapp_phone_number_id": "whatsapp_phone_number_id"
  },
  "branch_id": "branch_id",
  "environment": "environment",
  "timezone": "timezone",
  "target_concurrency_limit": 1,
  "branch_name": "branch_name"
}
```

**SDK Code**

```python
import requests

url = "https://api.elevenlabs.io/v1/convai/batch-calling/submit"

payload = {
    "call_name": "call_name",
    "agent_id": "agent_id",
    "recipients": [{}]
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.elevenlabs.io/v1/convai/batch-calling/submit';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"call_name":"call_name","agent_id":"agent_id","recipients":[{}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

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

func main() {

	url := "https://api.elevenlabs.io/v1/convai/batch-calling/submit"

	payload := strings.NewReader("{\n  \"call_name\": \"call_name\",\n  \"agent_id\": \"agent_id\",\n  \"recipients\": [\n    {}\n  ]\n}")

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

	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/convai/batch-calling/submit")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"call_name\": \"call_name\",\n  \"agent_id\": \"agent_id\",\n  \"recipients\": [\n    {}\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/convai/batch-calling/submit")
  .header("Content-Type", "application/json")
  .body("{\n  \"call_name\": \"call_name\",\n  \"agent_id\": \"agent_id\",\n  \"recipients\": [\n    {}\n  ]\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/convai/batch-calling/submit', [
  'body' => '{
  "call_name": "call_name",
  "agent_id": "agent_id",
  "recipients": [
    {}
  ]
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.elevenlabs.io/v1/convai/batch-calling/submit");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"call_name\": \"call_name\",\n  \"agent_id\": \"agent_id\",\n  \"recipients\": [\n    {}\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "call_name": "call_name",
  "agent_id": "agent_id",
  "recipients": [[]]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/batch-calling/submit")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```