Skip to main content
POST
/
batch-calls
curl -X POST "https://api.magpipe.ai/functions/v1/batch-calls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "name": "Appointment Reminders",
    "caller_id": "+16045551234",
    "send_now": true,
    "window_start_time": "09:00",
    "window_end_time": "17:00",
    "window_days": [1, 2, 3, 4, 5],
    "reserved_concurrency": 5,
    "recipients": [
      { "name": "John Doe", "phone_number": "+14155551234" },
      { "name": "Jane Smith", "phone_number": "+12125559876" }
    ]
  }'

{
  "batch": {
    "id": "f1e2d3c4-5678-9012-3456-789012345678",
    "user_id": "a1b2c3d4-user-uuid-here",
    "name": "Appointment Reminders",
    "caller_id": "+16045551234",
    "status": "running",
    "send_now": true,
    "total_recipients": 2,
    "completed_count": 0,
    "failed_count": 0,
    "created_at": "2024-02-15T09:00:00.000Z"
  }
}
Creates a new batch call campaign with a list of recipients. You can send immediately, schedule for later, or save as a draft.
Each dial costs $0.005 plus standard per-minute calling charges.

​
Body Parameters

​
action
string
required
Must be create
​
name
string
required
Name for the batch campaign.Example: "Appointment Reminders - January"
​
caller_id
string
required
Your Magpipe phone number to use as caller ID. Must be an active number in your account.Example: "+16045551234"
​
agent_id
string
UUID of the agent to handle calls. If not provided, uses the agent assigned to the caller_id number.
​
recipients
array
required
Array of recipient objects. Each must have at least phone_number.
[
  { "name": "John Doe", "phone_number": "+14155551234" },
  { "name": "Jane Smith", "phone_number": "+12125559876" }
]
​
send_now
boolean
default:"true"
If true, starts calling immediately. If false, requires scheduled_at.
​
scheduled_at
string
ISO 8601 timestamp for when to start calling. Required when send_now is false.Example: "2024-02-15T09:00:00.000Z"
​
window_start_time
string
default:"00:00"
Earliest time of day to make calls (HH:MM format).Example: "09:00"
​
window_end_time
string
default:"23:59"
Latest time of day to make calls (HH:MM format).Example: "17:00"
​
window_days
array
default:"[0,1,2,3,4,5,6]"
Days of the week when calls can be made. 0=Sunday, 6=Saturday.Example (Mon-Fri): [1, 2, 3, 4, 5]
​
reserved_concurrency
integer
default:"5"
Number of concurrency slots reserved for non-batch calls (inbound, etc).
​
purpose
string
Call purpose passed to the agent.
​
goal
string
Call goal passed to the agent.

​
Response

​
batch
object
The created batch object.
curl -X POST "https://api.magpipe.ai/functions/v1/batch-calls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "name": "Appointment Reminders",
    "caller_id": "+16045551234",
    "send_now": true,
    "window_start_time": "09:00",
    "window_end_time": "17:00",
    "window_days": [1, 2, 3, 4, 5],
    "reserved_concurrency": 5,
    "recipients": [
      { "name": "John Doe", "phone_number": "+14155551234" },
      { "name": "Jane Smith", "phone_number": "+12125559876" }
    ]
  }'

{
  "batch": {
    "id": "f1e2d3c4-5678-9012-3456-789012345678",
    "user_id": "a1b2c3d4-user-uuid-here",
    "name": "Appointment Reminders",
    "caller_id": "+16045551234",
    "status": "running",
    "send_now": true,
    "total_recipients": 2,
    "completed_count": 0,
    "failed_count": 0,
    "created_at": "2024-02-15T09:00:00.000Z"
  }
}