Create Batch Call | Speechify API

curl -X POST https://api.speechify.ai/v1/agents/batch-calls \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Appointment reminders",
  "agent_id": "agent_01HS...",
  "recipients": [
    {
      "phone": "+14155551234",
      "dynamic_vars": {
        "first_name": "Alice",
        "appointment_date": "May 5th at 2pm"
      }
    },
    {
      "phone": "+14155555678",
      "dynamic_vars": {
        "first_name": "Bob",
        "appointment_date": "May 6th at 10am"
      }
    }
  ]
}'

{
  "batch": {
    "id": "batch_01kj8fy7kphhchfcfc230hgv12",
    "agent_id": "agent_01HS...",
    "name": "Appointment reminders",
    "status": "pending",
    "total": 2,
    "completed": 0,
    "failed": 0,
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
}

Dial a list of phone numbers through one of your voice agents in a single request. Each recipient can receive personalised dynamic variables that your agent prompt references via {{key}} placeholders. Batches can run immediately or be scheduled up to 30 days in advance.

Accepts application/json or multipart/form-data (with a CSV file). Max 1000 recipients per batch.

Dial a list of phone numbers through one of your voice agents in a single request. Each recipient can receive personalised dynamic variables that your agent prompt references via `{{key}}` placeholders. Batches can run immediately or be scheduled up to 30 days in advance. Accepts `application/json` or `multipart/form-data` (with a CSV file). Max 1000 recipients per batch.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Request

This endpoint expects an object.

namestringRequired

Human-readable batch name.

agent_idstringRequired

Agent that handles each call.

recipientslist of objectsRequired

phone_number_idstringOptional

Caller-ID override. Falls back to the agent’s bound number.

scheduled_atdatetimeOptional

Schedule the batch for a future time (RFC 3339). Omit to start immediately.

ringing_timeout_msintegerOptional1000-80000

Ringing timeout in milliseconds applied to every call in the batch (how long each recipient rings before the dial gives up). Range 1000-80000 (1-80s). Omit to use the 30s default. The console collects this in seconds and converts to milliseconds.

Response

Batch accepted for processing.

batchobject

A batch of outbound calls dispatched to a list of recipients.

Errors

400

Bad Request Error