> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ultravox.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Outbound Call Scheduler
> Schedule and manage batches of outbound calls automatically with concurrency control and retry handling.
Premium Feature
Outbound Call Scheduler is available on select plans.
See [https://ultravox.ai/pricing](https://ultravox.ai/pricing) for details.
The Outbound Call Scheduler enables you to create and manage batches of outbound calls that will be sent by Ultravox. This allows you to simplify your deployment and stop worrying about things like retry logic. Simply define a time window and upload your call list - Ultravox handles the rest.
## Overview
Outbound Call Scheduler eliminates the complexity of managing outbound call campaigns by:
* **Automatic Concurrency Management** - No more 429 errors from hitting rate limits
* **Flexible Scheduling** - Define time windows for when calls should be made
* **Automatic capacity reservation** - Save room for high priority or incoming calls while your campaign is running
* **Batch Management** - Track progress and control execution
Call Delivery Not Guaranteed
Unless your call batch is scheduled without an end date/time, using outbound call scheduler does not guarantee that all calls will be made. If capacity limitations result in calls not being made by the end of your window, those scheduled calls will have the `EXPIRED` status.
The system enforces limits on window size to ensure EXPIRED calls are uncommon.
## How It Works
Pick an agent and upload a batch of calls with a time window and configuration.
Ultravox processes calls within your specified window, maximizing allowed utilization.
Calls are either initiated automatically or via webhook notifications.
Track batch status and individual call outcomes.
## Creating a Scheduled Batch
Use the [Create Scheduled Batch](/api-reference/agents/agents-scheduled-batches-post) API to upload your call batch.
### Batch Parameters
Optional. The earliest time when calls in this batch can be initiated. If unset, calls will start immediately.
Optional. The latest time when calls in this batch can be initiated. If unset, calls will continue until all are processed.
If `windowEnd` is too close to `windowStart` or the current time, you'll receive a 400 error with the system's estimation
of the minimum window needed for the number of calls in your batch.
Optional. URL to notify when calls are ready to be initiated. Required if any call doesn't have an outgoing medium.
Optional. Secret for webhook request verification.
Array of call configurations. Each call can include:
* `medium` - Must be a valid call [medium](/api-reference/schema/call-definition#schema-medium)
* Automatic outgoing calls work with `sip`, `twilio`, `telnyx`, or `plivo`
* All other media require providing a webhook URL
* `templateContext` - Variables for agent template substitution
* `metadata` - Key-value pairs associated with the call
* `experimentalSettings` - Experimental call configuration
### Examples
When all calls in your batch have an `outgoing` medium, Ultravox initiates calls automatically.
```js Example: Creating a Scheduled Batch theme={null}
{
"windowStart": "2025-09-25T09:00:00Z",
"windowEnd": "2025-09-25T17:00:00Z",
"calls": [
{
"medium": {
"sip": {
"outgoing": {
"to": "sip:+15551234567@carrier.com",
"from": "Your Company"
}
}
},
"templateContext": {
"customerName": "John Doe",
"appointmentTime": "3 PM tomorrow"
},
"metadata": {
"customer_id": "12345",
"campaign": "appointment_reminders"
}
},
{
"medium": {
"twilio": {
"outgoing": {
"to": "+15551234567",
"from": "+15559876543"
}
}
},
"templateContext": {
"customerName": "Jane Smith",
"appointmentTime": "2 PM tomorrow"
},
"metadata": {
"customer_id": "67890",
"campaign": "appointment_reminders"
}
}
]
}
```
When calls don't have outgoing mediums or you want more control, Ultravox notifies your webhook when capacity is available and your call is created. Your endpoint's job is to then join and connect the call.
```js Example: Webhook Notification theme={null}
{
"webhookUrl": "https://your-server.com/call-ready",
"webhookSecret": "your-secret-key",
"calls": [
{
"medium": {"webRtc": {}},
"templateContext": { "customerName": "John" },
"metadata": { "phone": "+15551234567" }
}
]
}
```
Your webhook receives the payload for the [call.started](/webhooks/available-webhooks#event-payload-reference) webhook event:
```js Call Definition Webhook Payload theme={null}
{
"event": "call.started",
"call": {
"callId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created": "2023-11-07T05:31:56Z",
"joined": "2023-11-07T05:31:56Z",
...
}
}
```
No Retries
Outbound call scheduler webhooks do not retry failed notifications. When your endpoint is unavailable, the system marks that delivery as "ERROR" and proceeds to the next scheduled call after a delay period.
## Managing Batches
### Monitor Batch Progress
Use [Get Scheduled Batch](/api-reference/agents/agents-scheduled-batches-get) to check status:
```js Response Example theme={null}
{
"batchId": "uuid",
"totalCount": 1000,
"completedCount": 750,
"windowStart": "2024-01-15T09:00:00Z",
"windowEnd": "2024-01-15T17:00:00Z",
"paused": false,
"endedAt": null
}
```
### List Scheduled Calls
View individual calls with [List Scheduled Calls](/api-reference/agents/agents-scheduled-batches-scheduled-calls-list):
```bash theme={null}
GET /api/agents/{agent_id}/scheduled_batches/{batch_id}/scheduled_calls?status=SUCCESS
```
### List Created Calls
See completed calls with [List Created Calls](/api-reference/agents/agents-scheduled-batches-created-calls-list):
```bash theme={null}
GET /api/agents/{agent_id}/scheduled_batches/{batch_id}/created_calls
```
### Pause a Batch
Use [Update Scheduled Batch](/api-reference/agents/agents-scheduled-batches-patch) to pause execution:
```js Pause Batch theme={null}
{
"paused": true
}
```
No Resume Function
Once paused, batches cannot currently be resumed. Pausing effectively stops processing without deleting the batch.
### Delete a Batch
Use [Delete Scheduled Batch](/api-reference/agents/agents-scheduled-batches-delete) to remove a batch entirely.
## Limits and Considerations
### Request Limits
* **Call Count**: No specific limit on number of calls per batch
* **Request Size**: Maximum 32MB per batch request
* **Multiple Batches**: Create additional batches if your request size is > 32MB
### Time Windows
* Calls will only be processed during the specified window
* Use appropriate time zones in your ISO 8601 timestamps
* Consider business hours and time zones of your recipients
### Error Handling
* Monitor batch progress to identify systematic issues
* Completed calls have a status and will indicate any calls experiencing errors
## Next Steps
* Explore the [Scheduled Call Batch](/api-reference/agents/agents-scheduled-batches-list) APIs
* Explore [Template Context](/agents/making-calls#template-context-and-variables) for dynamic call personalization