Skip to main content
POST
/
create-batch-call
JavaScript
import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

const batchCallResponse = await client.batchCall.createBatchCall({
  from_number: '+14157774444',
  tasks: [{ to_number: '+12137774445' }],
});

console.log(batchCallResponse.batch_call_id);
{
  "batch_call_id": "batch_call_dbcc4412483ebfc348abb",
  "name": "First batch call",
  "from_number": "+14157774444",
  "scheduled_timestamp": 1735718400,
  "total_task_count": 123,
  "call_time_window": {
    "windows": [
      {
        "start": 540,
        "end": 1020
      }
    ],
    "timezone": "<string>",
    "day": [
      "Monday"
    ]
  }
}

Authorizations

​
Authorization
string
header
required

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Body

application/json
​
from_number
string
required

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

Example:

"+14157774444"

​
tasks
object[]
required

A list of individual call tasks to be executed as part of the batch call. Each task represents a single outbound call and includes details such as the recipient's phone number and optional dynamic variables to personalize the call content.

​
name
string

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

Example:

"First batch call"

​
trigger_timestamp
number

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

Example:

1735718400000

​
reserved_concurrency
integer

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

Required range: x >= 0
​
call_time_window
object

Allowed calling windows in a specific timezone. Each window is a half-open interval [startMin, endMin) in minutes since 00:00 local time. Cross-midnight windows are NOT allowed (must satisfy startMin < endMin). endMin = 1440 (24:00) is valid.

Response

Successfully created a batch call.

​
batch_call_id
string
required

Unique id of the batch call.

Example:

"batch_call_dbcc4412483ebfc348abb"

​
name
string
required
Example:

"First batch call"

​
from_number
string
required
Example:

"+14157774444"

​
scheduled_timestamp
number
required
Example:

1735718400

​
total_task_count
number
required

Number of tasks within the batch call

​
call_time_window
object

Canonicalized minutes-based time windows. Present only if specified when the batch call was created or updated. See CallTimeWindow for format details ([startMin, endMin) in local minutes; no cross-midnight).