Skip to main content
Premium Feature
Outbound Call Scheduler is available on select plans.See https://ultravox.ai/pricing for details.
The Outbound Call Scheduler (OCS) 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

The OCS 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 OCS 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.

​
How It Works

1

Create a Scheduled Batch

Pick an agent and upload a batch of calls with a time window and configuration.
2

Automatic Processing

Ultravox processes calls within your specified window, maximizing allowed utilization.
3

Call Execution

Calls are either initiated automatically or via webhook notifications.
4

Monitor Progress

Track batch status and individual call outcomes.

​
Creating a Scheduled Batch

Use the Create Scheduled Batch API to upload your call batch.

​
Batch Parameters

​
windowStart
string
The earliest time when calls in this batch can be initiated.
​
windowEnd
string
The latest time when calls in this batch can be initiated.
​
webhookUrl
string
Optional. URL to notify when calls are ready to be initiated. Required if any call doesn’t have an outgoing medium.
​
webhookSecret
string
Optional. Secret for webhook request verification. Auto-generated if not provided.
​
calls
array
required
Array of call configurations. Each call can include:
  • medium - Must be a valid call medium
    • Automatic outgoing calls work with sip, twilio, telnyx, or plivo
    • webRtc or serverWebSocket require providing a webhook URL
  • templateContext - Variables for agent template substitution
  • metadata - Key-value pairs associated with the call
  • experimentalSettings - Advanced call configuration

​
Examples

  • Creating a Batch
  • Example: Webhook Notification
When all calls in your batch have an outgoing medium, Ultravox initiates calls automatically.
Example: Creating a Scheduled Batch
{
  "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"
      }
    }
  ]
}

​
Managing Batches

​
Monitor Batch Progress

Use Get Scheduled Batch to check status:
Response Example
{
  "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: 
GET /api/agents/{agent_id}/scheduled_batches/{batch_id}/scheduled_calls?status=SUCCESS

​
List Created Calls

See completed calls with List Created Calls: 
GET /api/agents/{agent_id}/scheduled_batches/{batch_id}/created_calls

​
Pause a Batch

Use Update Scheduled Batch to pause execution:
Pause Batch
{
  "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 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