Campaign Management

Creating & Scheduling Campaigns

Configure how your campaigns run, when calls are allowed, and how retries are handled.

The Campaign API combines scheduling, retry logic, recipient management, and operational controls into a single workflow.

Campaign Creation Flow

1. Configure

Define agent, scheduling rules, retries, and recipient data.

Create Campaign

Submit the campaign using the Create Campaign API.

Queue Generated

Vozzo prepares scheduling queues and initializes the campaign.

Start Dialing

Update the campaign state to RUNNING.

Campaign Payload Structure

The request body is divided into three main sections:

Code
 
campaign
 ├── root configuration
 ├── campaign_config
 └── campaign_data

Root Parameters

Parameter	Required	Description
`agent_uuid`	Yes	AI Voice Agent used for calls
`campaign_start_date`	Yes	Date campaign begins
`campaign_end_date`	No	Optional campaign end date
`campaign_config`	Yes	Scheduling and retry settings
`campaign_data`	Yes	Recipient call records

campaign_config

Controls retry behavior, time windows, and dialing rules.

Retry Settings

Parameter	Description
`max_calls_total`	Maximum attempts per recipient
`max_calls_in_a_day`	Daily retry cap
`retry_delay`	Delay before retrying failed calls

Timeslot Settings

Parameter	Description
`timezone`	Timezone used for scheduling
`start_time`	Daily dialing start hour
`end_time`	Daily dialing end hour
`allow_on_weekends`	Enable or disable weekend calling

campaign_data

Each item represents a recipient queued for outbound calling.


Code
 
{
  "to_phone_number": "+919876543210",
  "agent_language": "EN",
  "metadata": "{\"customer_name\":\"John Doe\"}"
}

Supported Fields

Field	Description
`to_phone_number`	Recipient number in E.164 format
`agent_language`	Voice agent language
`metadata`	Stringified JSON used for personalization

Example Campaign Request


Code
 
{
  "agent_uuid": "619ec26c-4957-4926-70f8-fe7391b3527e",

  "campaign_start_date": "2026-12-01",
  "campaign_end_date": "2026-12-31",

  "campaign_config": {
    "campaign_name": "Winter Promotion",

    "retry_options": {
      "max_calls_total": 3,
      "max_calls_in_a_day": 1,
      "retry_delay": 60
    },

    "timeslot_settings": {
      "timezone": "IST",
      "allow_on_weekends": false,
      "start_time": "09",
      "end_time": "18"
    }
  },

  "campaign_data": [
    {
      "to_phone_number": "+911234567890",
      "agent_language": "EN",
      "metadata": "{\"customer_name\":\"John Doe\"}"
    }
  ]
}

Scheduling Rules

The scheduling engine ensures calls are placed only during allowed windows.

Timezone Aware

Calling windows are evaluated using the configured timezone.

Daily Time Windows

Calls only start between configured start and end hours.

Weekend Controls

Prevent outbound dialing on weekends when disabled.

Retry Logic

Retries are automatically scheduled when calls fail, are busy, or unanswered.

Example Configuration


Code
 
{
  "max_calls_total": 3,
  "max_calls_in_a_day": 1,
  "retry_delay": 3600
}

Example Flow

Code
 
Day 1 → Attempt 1 → No Answer
↓
Wait 1 Hour
↓
Daily Limit Reached
↓
Deferred to Next Day
↓
Attempt 2
↓
Attempt 3
↓
Completed

Validation Rules

The API validates requests before campaigns are created.

Date Validation:

Start dates must be today or in the future.

Retry Limits:

max_calls_total must be between 1 and 5.

Phone Format:

Phone numbers must follow E.164 format.

Metadata:

metadata must contain valid stringified JSON.

Recommended Best Practices

• Disable weekend calling for promotional campaigns.
• Use metadata for personalized introductions and contextual conversations.
• Use retry limits to prevent excessive outbound attempts.
• Keep calling windows aligned with local business hours.

Create Campaign

Code
 
POST /v1alpha/campaign

Update Campaign

Code
 
POST /v1alpha/campaign/update-campaign/{campaign_id}/

Get Scheduled Calls

Code
 
GET /v1alpha/campaign/{campaign_id}/items

Call Item Details

Code
 
GET /v1alpha/campaign/{campaign_id}/item/{scheduled_item_id}

Next Steps

Managing Campaigns

Pause, resume, update, and monitor live campaigns.

Retry & Time Intelligence

Learn advanced retry patterns and scheduling optimization.

Campaign API • v1alpha

Last modified on July 24, 2026

APIs & Data Export Managing Campaigns

Campaign Management

Creating & Scheduling Campaigns

Configure how your campaigns run, when calls are allowed, and how retries are handled.

The Campaign API combines scheduling, retry logic, recipient management, and operational controls into a single workflow.

Campaign Creation Flow

1. Configure

Define agent, scheduling rules, retries, and recipient data.

Create Campaign

Submit the campaign using the Create Campaign API.

Queue Generated

Vozzo prepares scheduling queues and initializes the campaign.

Start Dialing

Update the campaign state to RUNNING.

Campaign Payload Structure

The request body is divided into three main sections:

Code
 
campaign
 ├── root configuration
 ├── campaign_config
 └── campaign_data

Root Parameters

Parameter	Required	Description
`agent_uuid`	Yes	AI Voice Agent used for calls
`campaign_start_date`	Yes	Date campaign begins
`campaign_end_date`	No	Optional campaign end date
`campaign_config`	Yes	Scheduling and retry settings
`campaign_data`	Yes	Recipient call records

campaign_config

Controls retry behavior, time windows, and dialing rules.

Retry Settings

Parameter	Description
`max_calls_total`	Maximum attempts per recipient
`max_calls_in_a_day`	Daily retry cap
`retry_delay`	Delay before retrying failed calls

Timeslot Settings

Parameter	Description
`timezone`	Timezone used for scheduling
`start_time`	Daily dialing start hour
`end_time`	Daily dialing end hour
`allow_on_weekends`	Enable or disable weekend calling

campaign_data

Each item represents a recipient queued for outbound calling.


Code
 
{
  "to_phone_number": "+919876543210",
  "agent_language": "EN",
  "metadata": "{\"customer_name\":\"John Doe\"}"
}

Supported Fields

Field	Description
`to_phone_number`	Recipient number in E.164 format
`agent_language`	Voice agent language
`metadata`	Stringified JSON used for personalization

Example Campaign Request


Code
 
{
  "agent_uuid": "619ec26c-4957-4926-70f8-fe7391b3527e",

  "campaign_start_date": "2026-12-01",
  "campaign_end_date": "2026-12-31",

  "campaign_config": {
    "campaign_name": "Winter Promotion",

    "retry_options": {
      "max_calls_total": 3,
      "max_calls_in_a_day": 1,
      "retry_delay": 60
    },

    "timeslot_settings": {
      "timezone": "IST",
      "allow_on_weekends": false,
      "start_time": "09",
      "end_time": "18"
    }
  },

  "campaign_data": [
    {
      "to_phone_number": "+911234567890",
      "agent_language": "EN",
      "metadata": "{\"customer_name\":\"John Doe\"}"
    }
  ]
}

Scheduling Rules

The scheduling engine ensures calls are placed only during allowed windows.

Timezone Aware

Calling windows are evaluated using the configured timezone.

Daily Time Windows

Calls only start between configured start and end hours.

Weekend Controls

Prevent outbound dialing on weekends when disabled.

Retry Logic

Retries are automatically scheduled when calls fail, are busy, or unanswered.

Example Configuration


Code
 
{
  "max_calls_total": 3,
  "max_calls_in_a_day": 1,
  "retry_delay": 3600
}

Example Flow

Code
 
Day 1 → Attempt 1 → No Answer
↓
Wait 1 Hour
↓
Daily Limit Reached
↓
Deferred to Next Day
↓
Attempt 2
↓
Attempt 3
↓
Completed

Validation Rules

The API validates requests before campaigns are created.

Date Validation:

Start dates must be today or in the future.

Retry Limits:

max_calls_total must be between 1 and 5.

Phone Format:

Phone numbers must follow E.164 format.

Metadata:

metadata must contain valid stringified JSON.

Recommended Best Practices

• Disable weekend calling for promotional campaigns.
• Use metadata for personalized introductions and contextual conversations.
• Use retry limits to prevent excessive outbound attempts.
• Keep calling windows aligned with local business hours.

Create Campaign

Code
 
POST /v1alpha/campaign

Update Campaign

Code
 
POST /v1alpha/campaign/update-campaign/{campaign_id}/

Get Scheduled Calls

Code
 
GET /v1alpha/campaign/{campaign_id}/items

Call Item Details

Code
 
GET /v1alpha/campaign/{campaign_id}/item/{scheduled_item_id}

Next Steps

Managing Campaigns

Pause, resume, update, and monitor live campaigns.

Retry & Time Intelligence

Learn advanced retry patterns and scheduling optimization.

Campaign API • v1alpha

Last modified on July 24, 2026

APIs & Data Export Managing Campaigns

Campaign Creation Flow

1. Configure

Create Campaign

Queue Generated

Start Dialing

Campaign Payload Structure

Root Parameters

campaign_config

Retry Settings

Timeslot Settings

campaign_data

Supported Fields

Example Campaign Request

Scheduling Rules

Timezone Aware

Daily Time Windows

Weekend Controls

Retry Logic

Example Configuration

Example Flow

Validation Rules

Recommended Best Practices

Related APIs

Create Campaign

Update Campaign

Get Scheduled Calls

Call Item Details

Next Steps

Managing Campaigns

Retry & Time Intelligence

Campaign Creation Flow

1. Configure

Create Campaign

Queue Generated

Start Dialing

Campaign Payload Structure

Root Parameters

campaign_config

Retry Settings

Timeslot Settings

campaign_data

Supported Fields

Example Campaign Request

Scheduling Rules

Timezone Aware

Daily Time Windows

Weekend Controls

Retry Logic

Example Configuration

Example Flow

Validation Rules

Recommended Best Practices

Related APIs

Create Campaign

Update Campaign

Get Scheduled Calls

Call Item Details

Next Steps

Managing Campaigns

Retry & Time Intelligence