Skip to main content
POST
/
v1
/
voiceai
/
batch-calling
/
submit
Submit A Batch Call Request
curl --request POST \
  --url https://api.example.com/v1/voiceai/batch-calling/submit \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "call_name": "<string>",
  "agent_id": "<string>",
  "recipients": [
    {
      "id": "<string>",
      "phone_number": "<string>",
      "whatsapp_user_id": "<string>",
      "conversation_initiation_client_data": {
        "conversation_config_override": {
          "turn": {
            "soft_timeout_config": {
              "message": "<string>"
            }
          },
          "tts": {
            "voice_id": "<string>",
            "stability": 123,
            "speed": 123,
            "similarity_boost": 123
          },
          "conversation": {
            "text_only": true
          },
          "agent": {
            "first_message": "<string>",
            "language": "<string>",
            "prompt": {
              "prompt": "<string>",
              "llm": "<string>",
              "native_mcp_server_ids": [
                "<string>"
              ]
            }
          }
        },
        "custom_llm_extra_body": {},
        "user_id": "<string>",
        "source_info": {
          "source": "unknown",
          "version": "<string>"
        },
        "dynamic_variables": {}
      }
    }
  ]
}
'
{
  "id": "<string>",
  "name": "<string>",
  "agent_id": "<string>",
  "created_at_unix": 123,
  "scheduled_time_unix": 123,
  "last_updated_at_unix": 123,
  "status": "pending",
  "agent_name": "<string>",
  "phone_number_id": "<string>",
  "phone_provider": "twilio",
  "whatsapp_params": {
    "whatsapp_call_permission_request_template_name": "<string>",
    "whatsapp_call_permission_request_template_language_code": "<string>",
    "whatsapp_phone_number_id": "<string>"
  },
  "total_calls_dispatched": 0,
  "total_calls_scheduled": 0,
  "total_calls_finished": 0,
  "retry_count": 0
}

Authorizations

x-api-key
string
header
required

API key for programmatic access

Body

application/json

Request model for submitting a batch call job.

call_name
string
required

Name of the batch call job

agent_id
string
required

Agent ID to use for calls

recipients
OutboundCallRecipient · object[]
required

List of recipients to call

Maximum array length: 10000
scheduled_time_unix
integer | null

Unix timestamp to schedule the batch call (None = immediate)

agent_phone_number_id
string | null

Caller phone number ID (from your purchased numbers)

whatsapp_params
BatchCallWhatsAppParams · object

WhatsApp parameters (future support)

Response

Successful Response

Response model for a single batch call job.

id
string
required

Unique batch call ID

name
string
required

Name of the batch call job

agent_id
string
required

Agent ID to use for calls

created_at_unix
integer
required

Unix timestamp when created

scheduled_time_unix
integer
required

Unix timestamp when scheduled to start

last_updated_at_unix
integer
required

Unix timestamp of last update

status
enum<string>
required

Current status of the batch job

Available options:
pending,
in_progress,
completed,
failed,
cancelled
agent_name
string
required

Name of the agent

phone_number_id
string | null

Caller phone number ID

phone_provider
enum<string> | null

Telephony provider for batch calls.

Available options:
twilio,
vobiz,
sip_trunk
whatsapp_params
BatchCallWhatsAppParams · object

WhatsApp parameters for batch calls (future support).

total_calls_dispatched
integer
default:0

Number of calls dispatched

total_calls_scheduled
integer
default:0

Number of calls scheduled

total_calls_finished
integer
default:0

Number of calls finished (completed + failed)

retry_count
integer
default:0

Number of retries attempted