Bulk Call
The Bulk Call module allows you to create, manage, and monitor bulk calling campaigns. You can schedule calls for multiple contacts, pause/resume campaigns, and track their progress.
Overview
The Bulk Call API enables you to manage large-scale calling campaigns:
- Create bulk calling campaigns with multiple contacts
- Schedule campaigns for future execution
- Configure automatic retry for failed calls
- Pause, resume, and reschedule active campaigns
- Cancel campaigns before or during execution
- Monitor campaign status and progress
- Retrieve detailed campaign information and contact lists
List Bulk Calls
Retrieve a list of all bulk call campaigns with pagination and optional filtering.
Parameters
Page number for pagination (default: 1)
Number of items per page (default: 10)
Filter bulk calls by status
Example
1
2
3
4
5
6
7
# Fetch all bulk calls with pagination
response = client.bulk_call.fetch_bulk_calls(page=1, page_size=10)
print(response)
# Filter bulk calls by status
response = client.bulk_call.fetch_bulk_calls(page=1, page_size=10, status="completed")
print(response)Note
Create Bulk Call
Create a new bulk calling campaign with a list of contacts.
Parameters
Name of the bulk call campaign
Array of contact objects with phone numbers and optional context data
Your phone number id to use for making calls
Whether the campaign should be scheduled for future execution (default: false)
Scheduled execution time in format 'YYYY-MM-DD HH:MM:SS' (required if is_scheduled is true)
Timezone for scheduled execution (default: 'UTC')
Auto retry configuration object containing retry settings
Enable automatic call rescheduling functionality (default: false). When enabled system will automatically able to reschedule the call to the requested time.
Maximum number of concurrent calls allowed (default: 1)
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
# Create an immediate bulk call with auto-retry
bulk_call_data = {
"name": "Customer Follow-up Campaign",
"contact_list": [
{
"phone_number": "+15551234567",
"customer_name": "John Doe",
"account_id": "ACC-12345"
},
{
"phone_number": "+15559876543",
"customer_name": "Jane Smith",
"account_id": "ACC-67890"
}
],
"phone_number_id": 1, # get the from number id from phone number API. /api/v1/phone_number/list
"is_scheduled": False,
"retry_config": {
"auto_retry": True,
"auto_retry_schedule": "next_day",
"retry_limit": 2
},
"enabled_reschedule_call": True
}
response = client.bulk_call.create_bulk_call(bulk_call_data)
print(response)
# Create a scheduled bulk call
scheduled_bulk_call_data = {
"name": "Scheduled Marketing Campaign",
"contact_list": [
{
"phone_number": "+15551234567",
"customer_name": "John Doe",
"priority": "high"
}
],
"phone_number_id": 1, # get the from number id from phone number API. /api/v1/phone_number/list
"is_scheduled": True,
"scheduled_datetime": "2024-12-25 10:00:00",
"timezone": "America/New_York",
}
response = client.bulk_call.create_bulk_call(scheduled_bulk_call_data)
print(response)
# Create bulk call with scheduled retry (retry after 2 days and 6 hours) and enabled reschedule call
scheduled_retry_bulk_call_data = {
"name": "Follow-up Campaign with Scheduled Retry",
"contact_list": [
{
"phone_number": "+15551234567",
"customer_name": "John Doe"
}
],
"phone_number_id": 1,
"is_scheduled": False,
"retry_config": {
"auto_retry": True,
"auto_retry_schedule": "scheduled_time",
"retry_schedule_days": 2,
"retry_schedule_hours": 6,
"retry_limit": 2
},
"enabled_reschedule_call": True
}
response = client.bulk_call.create_bulk_call(scheduled_retry_bulk_call_data)
print(response)Note
Phone Number Format: All phone numbers must include the country code with a leading plus sign (e.g., +15551234567).
Scheduling: When scheduling a campaign, the scheduled_datetime must be in the future. The system will convert the time to UTC for storage.
Phone Number ID: Voice Agent Bot Attached With The Phone Number Will Be Used To Make Calls.
Contact List: Each contact can include additional context data that will be passed to the agent during the call.
Auto Retry Configuration: Pass retry settings in the 'retry_config' object. When auto_retry is enabled, failed calls will be automatically retried based on the specified schedule. Maximum retry limit is 5 attempts.
Retry Schedule: Choose when to retry: 'immediately' (retry right away), 'next_day' (retry the next day), or 'scheduled_time' (retry after specified days/hours). When using 'scheduled_time', you must provide retry_schedule_days and retry_schedule_hours values.
Scheduled Time Parameters: When auto_retry_schedule is set to 'scheduled_time', both retry_schedule_days and retry_schedule_hours are required to specify the exact retry timing.
Call Rescheduling: When enabled_reschedule_call is set to true, the AI agent can automatically reschedule calls during conversations. If a user requests to be called back at a specific time (e.g., "Can you call me tomorrow at 3 PM?"), the system will automatically create a new scheduled call for that requested time and mark the current call as rescheduled.
Bulk Call Actions
Perform actions on existing bulk call campaigns (pause, resume, reschedule).
Parameters
ID of the bulk call campaign
Action to perform on the bulk call
New scheduled time in format 'YYYY-MM-DD HH:MM:SS' (required for reschedule action)
New timezone for rescheduled execution (optional, defaults to existing timezone)
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# Pause a bulk call
response = client.bulk_call.bulk_call_actions(
bulk_call_id=123,
action="pause"
)
print(response)
# Resume a bulk call
response = client.bulk_call.bulk_call_actions(
bulk_call_id=123,
action="resume"
)
print(response)
# Reschedule a bulk call
response = client.bulk_call.bulk_call_actions(
bulk_call_id=123,
action="reschedule",
new_scheduled_datetime="2024-12-26 14:00:00",
new_timezone="America/Los_Angeles"
)
print(response)Note
Pause: Stops the campaign execution. Can be resumed later.
Resume: Continues a paused campaign from where it left off.
Reschedule: Changes the scheduled time for a campaign. The new time must be in the future.
Cancel Bulk Call
Cancel a bulk call campaign permanently.
Parameters
ID of the bulk call campaign to cancel
Example
1
2
3
# Cancel a bulk call
response = client.bulk_call.cancel_bulk_call(bulk_call_id=123)
print(response)Note
Get Bulk Call Details
Get detailed information about a specific bulk call campaign.
Parameters
ID of the bulk call campaign to retrieve
Example
1
2
3
# Get detailed information about a bulk call
response = client.bulk_call.detail_bulk_call(bulk_call_id=123)
print(response)Note
Response Formats
Success Response
{
"status": "success",
"message": "Bulk call created successfully",
"id": 123,
"is_scheduled": false,
"current_status": "draft"
}Error Response
{
"status": "error",
"message": "Error: Phone Number does not belong to user"
}Bulk Call List Response
{
"status": "success",
"records": [
{
"id": 123,
"name": "Customer Follow-up Campaign",
"status": "in_progress",
"is_scheduled": false,
"created_at": "2024-01-15T10:30:00Z",
"total_contacts": 50,
"completed_calls": 25,
"failed_calls": 2
}
],
"total_records": 1
}Campaign Statuses
Campaign has been created but not yet started
Campaign is scheduled for future execution
Campaign is currently executing calls
Campaign execution has been paused
All calls in the campaign have been processed successfully
Campaign execution failed due to errors
Campaign has been cancelled and will not execute