curl -X POST 'https://api.elevenlabs.io/v1/convai/batch-calling/submit' \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "call_name": "example-call-name",
  "agent_id": "agent-id",
  "recipients": [
    {
      "id": "example-id",
      "phone_number": "example-phone-number",
      "whatsapp_user_id": "example-whatsapp-user-id",
      "conversation_initiation_client_data": {
        "conversation_config_override": {
          "agent": {
            "first_message": "Hello, how can I help you today?",
            "language": "en",
            "prompt": {
              "knowledge_base": [],
              "llm": "gemini-2.0-flash-001",
              "prompt": "You are a helpful assistant that can answer questions about the topic of the conversation.",
              "tool_ids": []
            }
          },
          "asr": {
            "keywords": [
              "hello",
              "world"
            ]
          },
          "conversation": {
            "max_duration_seconds": 600
          },
          "tts": {
            "model_id": "eleven_turbo_v2",
            "pronunciation_dictionary_locators": [],
            "similarity_boost": 0.8,
            "speed": 1,
            "stability": 0.5,
            "voice_id": "cjVigY5qzO86Huf0OWal"
          },
          "turn": {
            "soft_timeout_config": {
              "message": "Hhmmmm...yeah."
            }
          }
        },
        "custom_llm_extra_body": {},
        "user_id": "example-user-id",
        "source_info": {
          "source": "unknown",
          "version": "example-version"
        },
        "branch_id": "example-branch-id",
        "environment": "example-environment",
        "starting_workflow_node_id": "example-starting-workflow-node-id",
        "procedure_ids": [
          "example-procedure-ids"
        ],
        "dynamic_variables": {}
      }
    }
  ],
  "scheduled_time_unix": 0,
  "agent_phone_number_id": "agent-phone-number-id",
  "whatsapp_params": {
    "whatsapp_phone_number_id": "example-whatsapp-phone-number-id",
    "whatsapp_call_permission_request_template_name": "example-whatsapp-call-permission-request-template-name",
    "whatsapp_call_permission_request_template_language_code": "example-whatsapp-call-permission-request-template-language-code"
  },
  "timezone": "example-timezone",
  "branch_id": "branch-id",
  "environment": "example-environment",
  "telephony_call_config": {
    "ringing_timeout_secs": 60,
    "twilio_call_recording_enabled": false,
    "twilio_machine_detection": {
      "mode": "enable",
      "actions": [
        {
          "action": "hang_up",
          "answered_by": [
            "[recursive or deeply nested schema]"
          ]
        }
      ]
    }
  },
  "target_concurrency_limit": 0
}'

# POST /v1/convai/batch-calling/submit (ElevenLabs API)
Base URL: https://api.elevenlabs.io
Auth: xi-api-key: <ELEVENLABS_API_KEY>
Last verified: 2026-10-20

> Submit A Batch Call Request.

## Critical Gotchas
* Authentication uses the non-standard `xi-api-key` header, not `Authorization: Bearer`. Sending a Bearer token returns HTTP 401.
* Text-to-speech responses are raw binary audio, not JSON. Write the body to a file (`--output speech.mp3`) rather than parsing it.

## cURL
curl -X POST 'https://api.elevenlabs.io/v1/convai/batch-calling/submit' \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"call_name":"example-call-name","agent_id":"agent-id","recipients":[{"id":"example-id","phone_number":"example-phone-number"}]}'

## Parameters
| Name | In | Type | Required | Description |
| :--- | :--- | :--- | :--- | :--- |
| call_name | body | string | Yes | Request body field call_name. |
| agent_id | body | string | Yes | Request body field agent_id. |
| recipients | body | object[] | Yes | Request body field recipients. |
Other params: scheduled_time_unix, agent_phone_number_id, whatsapp_params, timezone, branch_id, environment, telephony_call_config, target_concurrency_limit

## Response (200 OK)
{"id":"string","phone_number_id":"string"}

---
Need an API key? Get one at https://elevenlabs.io/app/sign-up

POST

POST /v1/convai/batch-calling/submit — ElevenLabs API

ElevenLabs API

Submit A Batch Call Request.

Base URL: https://api.elevenlabs.io
Auth: xi-api-key: <ELEVENLABS_API_KEY>
Last verified: 2026-10-20 · upstream hash matched

Actions Try in browser→

Agents: curl -H "Accept: text/markdown" this URL
→ 219 tokens · Vary: Accept

Critical gotchas

Authentication uses the non-standard xi-api-key header, not Authorization: Bearer. Sending a Bearer token returns HTTP 401.

Text-to-speech responses are raw binary audio, not JSON. Write the body to a file (--output speech.mp3) rather than parsing it.

cURL

curl -X POST 'https://api.elevenlabs.io/v1/convai/batch-calling/submit' \  -H "xi-api-key: $ELEVENLABS_API_KEY" \  -H 'Content-Type: application/json' \  -d '{  "call_name": "example-call-name",  "agent_id": "agent-id",  "recipients": [    {      "id": "example-id",      "phone_number": "example-phone-number",      "whatsapp_user_id": "example-whatsapp-user-id",      "conversation_initiation_client_data": {        "conversation_config_override": {          "agent": {            "first_message": "Hello, how can I help you today?",            "language": "en",            "prompt": {              "knowledge_base": [],              "llm": "gemini-2.0-flash-001",              "prompt": "You are a helpful assistant that can answer questions about the topic of the conversation.",              "tool_ids": []            }          },          "asr": {            "keywords": [              "hello",              "world"            ]          },          "conversation": {            "max_duration_seconds": 600          },          "tts": {            "model_id": "eleven_turbo_v2",            "pronunciation_dictionary_locators": [],            "similarity_boost": 0.8,            "speed": 1,            "stability": 0.5,            "voice_id": "cjVigY5qzO86Huf0OWal"          },          "turn": {            "soft_timeout_config": {              "message": "Hhmmmm...yeah."            }          }        },        "custom_llm_extra_body": {},        "user_id": "example-user-id",        "source_info": {          "source": "unknown",          "version": "example-version"        },        "branch_id": "example-branch-id",        "environment": "example-environment",        "starting_workflow_node_id": "example-starting-workflow-node-id",        "procedure_ids": [          "example-procedure-ids"        ],        "dynamic_variables": {}      }    }  ],  "scheduled_time_unix": 0,  "agent_phone_number_id": "agent-phone-number-id",  "whatsapp_params": {    "whatsapp_phone_number_id": "example-whatsapp-phone-number-id",    "whatsapp_call_permission_request_template_name": "example-whatsapp-call-permission-request-template-name",    "whatsapp_call_permission_request_template_language_code": "example-whatsapp-call-permission-request-template-language-code"  },  "timezone": "example-timezone",  "branch_id": "branch-id",  "environment": "example-environment",  "telephony_call_config": {    "ringing_timeout_secs": 60,    "twilio_call_recording_enabled": false,    "twilio_machine_detection": {      "mode": "enable",      "actions": [        {          "action": "hang_up",          "answered_by": [            "[recursive or deeply nested schema]"          ]        }      ]    }  },  "target_concurrency_limit": 0}'

Parameters

Name	In	Type	Required	Description
call_name	body	string	Yes	Request body field call_name.
agent_id	body	string	Yes	Request body field agent_id.
recipients	body	object[]	Yes	Request body field recipients.
scheduled_time_unix	body	integer	No	Request body field scheduled_time_unix.
agent_phone_number_id	body	string	No	Request body field agent_phone_number_id.
whatsapp_params	body	object	No	Request body field whatsapp_params.
timezone	body	string	No	Request body field timezone.
branch_id	body	string	No	Request body field branch_id.
environment	body	string	No	Request body field environment.
telephony_call_config	body	object	No	Request body field telephony_call_config.
target_concurrency_limit	body	integer	No	Maximum number of simultaneous calls for this batch. When set, dispatch is governed by this limit rather than workspace/agent capacity percentages.

Response 200 OK

{
  "id": "string",
  "phone_number_id": "string",
  "phone_provider": "twilio",
  "whatsapp_params": {
    "whatsapp_phone_number_id": "string",
    "whatsapp_call_permission_request_template_name": "string",
    "whatsapp_call_permission_request_template_language_code": "string"
  },
  "name": "string",
  "agent_id": "string",
  "branch_id": "string",
  "environment": "string",
  "created_at_unix": 0,
  "scheduled_time_unix": 0,
  "timezone": "string",
  "total_calls_dispatched": 0,
  "total_calls_scheduled": 0,
  "total_calls_finished": 0,
  "last_updated_at_unix": 0,
  "status": "pending",
  "retry_count": 0,
  "telephony_call_config": {
    "ringing_timeout_secs": 60,
    "twilio_call_recording_enabled": false,
    "twilio_machine_detection": {
      "mode": "enable",
      "actions": [
        {
          "action": "hang_up",
          "answered_by": [
            "[recursive or deeply nested schema]"
          ]
        }
      ]
    }
  },
  "target_concurrency_limit": 0,
  "agent_name": "string",
  "branch_name": "string"
}

Get a free ElevenLabs API key → sponsored

Affiliate link - we may earn a commission, at no extra cost to you.