Skip to main content
PUT
/
api
/
v1
/
campaigns
/
{campaign_id}
# Update only the call windows + timezone
curl -X PUT "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "call_time_ranges": [
      {"start": "10:00", "end": "12:00"},
      {"start": "14:00", "end": "16:00"}
    ],
    "timezone": "America/Sao_Paulo"
  }'

{
  "success": true,
  "data": {
    "id": "campaign-uuid-1",
    "name": "Sales Campaign Q1",
    "campaign_type": "sales",
    "status": "active",
    "agent_id": "agent-uuid-1",
    "start_date": "2024-01-01",
    "end_date": null,
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
      {"start": "10:00", "end": "12:00"},
      {"start": "14:00", "end": "16:00"}
    ],
    "timezone": "America/Sao_Paulo",
    "max_retries": 3,
    "retry_cooldown_hours": 24,
    "do_not_call_enabled": false,
    "updated_at": "2024-01-15T11:30:00Z"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Update Campaign

Partially update an existing campaign. All fields are optional — only the fields you send are updated. Use Update Campaign Status instead to change just the status (draft → active → paused → completed).

​
Endpoint

PUT /api/v1/campaigns/{campaign_id}

​
Path Parameters

​
campaign_id
string
required
UUID of the campaign to update.

​
Request Headers

​
Authorization
string
required
Bearer token for authentication. Format: Bearer talq_your_environment_token_here
​
Content-Type
string
required
Must be set to application/json

​
Request Body

All fields are optional. Send only what you want to change. Validation rules and ranges match Create Campaign.

​
Identification

​
name
string
Campaign name. Max 255 characters.
​
description
string
Free-form description.
​
campaign_type
string
Campaign category. Options: sales, follow_up, reminder, custom.
​
agent_id
string
UUID of the agent. Must exist in your environment.

​
Schedule

​
start_date
string
Format: YYYY-MM-DD.
​
end_date
string
Optional end date. Must be after start_date. Format: YYYY-MM-DD. Send null to clear.
​
days_of_week
array
Array of weekday numbers (1–7, where 1 = Monday). Min 1 entry.
​
call_time_ranges
array
Time windows. Array of {start: "HH:MM", end: "HH:MM"} objects (24h format). Min 1 entry. Each window’s end must be after its start.
​
timezone
string
IANA timezone (e.g., America/New_York). Max 50 characters.

​
Retry & Cooldown

​
initial_call_delay
integer
Initial delay in seconds. Range: 0+.
​
max_retries
integer
Range: 0–10.
​
retry_cooldown_hours
integer
Range: 1–168.
​
auto_complete
boolean
Auto-transition to completed when all contacts are processed.
​
retry_on_no_conversion
boolean
Retry calls that completed without conversion.
​
enable_post_completion_cooldown
boolean
​
post_completion_cooldown_hours
integer
Range: 1–168.
​
success_cooldown_hours
integer
Range: 1–168.
​
voicemail_cooldown_hours
integer
Range: 1–168.
​
no_answer_cooldown_hours
integer
Range: 1–168.
​
busy_cooldown_hours
integer
Range: 1–168.
​
failed_cooldown_hours
integer
Range: 1–168.

​
Do-Not-Call (DNC)

​
do_not_call_enabled
boolean
​
do_not_call_list_source
string
Options: environment, global, custom.
​
do_not_call_custom_list
array
Array of phone numbers (E.164). Used when do_not_call_list_source is custom.
​
auto_add_to_dnc_enabled
boolean
​
auto_dnc_trigger_statuses
array
​
auto_dnc_trigger_errors
array

​
Examples

# Update only the call windows + timezone
curl -X PUT "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "call_time_ranges": [
      {"start": "10:00", "end": "12:00"},
      {"start": "14:00", "end": "16:00"}
    ],
    "timezone": "America/Sao_Paulo"
  }'

# Switch to custom DNC list and tighten retry policy
curl -X PUT "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "max_retries": 2,
    "retry_cooldown_hours": 12,
    "success_cooldown_hours": 168,
    "do_not_call_enabled": true,
    "do_not_call_list_source": "custom",
    "do_not_call_custom_list": ["+15551234567"],
    "auto_add_to_dnc_enabled": true,
    "auto_dnc_trigger_statuses": ["completed"]
  }'

​
Response

​
Success Response (200 OK)

{
  "success": true,
  "data": {
    "id": "campaign-uuid-1",
    "name": "Sales Campaign Q1",
    "campaign_type": "sales",
    "status": "active",
    "agent_id": "agent-uuid-1",
    "start_date": "2024-01-01",
    "end_date": null,
    "days_of_week": [1, 2, 3, 4, 5],
    "call_time_ranges": [
      {"start": "10:00", "end": "12:00"},
      {"start": "14:00", "end": "16:00"}
    ],
    "timezone": "America/Sao_Paulo",
    "max_retries": 3,
    "retry_cooldown_hours": 24,
    "do_not_call_enabled": false,
    "updated_at": "2024-01-15T11:30:00Z"
  }
}

​
Error Responses

​
422 Validation Error

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "call_time_ranges.0.end": [
      "The call time ranges.0.end must be a date after call time ranges.0.start."
    ]
  }
}

​
404 Not Found

{
  "success": false,
  "message": "Campaign not found"
}

​
409 Conflict — Active Calls

{
  "success": false,
  "message": "Cannot update schedule while there are queued calls. Pause the campaign first.",
  "code": "CAMPAIGN_HAS_ACTIVE_CALLS"
}

​
Notes

  • Use PATCH /v1/campaigns/{id}/status to change status — it’s a separate endpoint with its own validation.
  • Updating call_time_ranges or timezone while the campaign is active may delay queued calls until they fall back into the new windows.
  • Sending "end_date": null clears a previously set end date.